Answer prose round 1: 1 🔴, 4 🟡 (0 misread); keep the seat sentence in the seat's rung rule, reword the skills' launch notes

This commit is contained in:
2026-11-17 09:36:33 +01:00
parent aa2815ba75
commit 970ecdb8a3
6 changed files with 16 additions and 16 deletions
+1 -1
View File
@@ -5,4 +5,4 @@ tools: Read, Grep, Glob, Bash
omitClaudeMd: true
---
You are a simulated reader of a project, and the prompt you are launched with says who: your background, the checkout you read, what you may open and the report to write. Read the project as that reader meets it, knowing only what its files tell you. Nothing here adds to the prompt; follow it exactly.
You are a simulated reader of a project. Your prompt gives your background, the checkout you read, the files you may not open and the report to write. Read as that reader would, knowing only what the project's files tell you, and follow the prompt exactly.
+3 -2
View File
@@ -93,8 +93,9 @@ skills/comprehension-panel/seat-prompts.md builds them. It prints the worktree's
prompt's. It takes {{language}}, {{kind}}, {{domain}}, {{domain docs}} and {{3am question}} from the
checkout's AGENTS.md → "Scoring run". claude-config keeps no AGENTS.md, so there it takes them from
seat-prompts.md → "claude-config's values". It fills the other placeholders from the worktree and
the panel's SKILL.md. Where any one of the five values is missing, it exits 1 and doesn't write anything. Where a setup that
record-scoring never removed is still there, it removes it first and says so.
the panel's SKILL.md. Where any one of the five values is missing, it exits 1 and doesn't write
anything. Where a setup that record-scoring never removed is still there, it removes it first and
says so.
record-scoring takes the scores file of a run needs-scoring-run calls, whose first line names no
`, against`, and the same item IDs, and exits 1 when they call no run. It appends the seats' scores
+1 -1
View File
@@ -22,7 +22,7 @@ SEATS = (
)
# The dimensions a seat scores beside the overall, which comes last in DIMENSIONS.
PANEL_DIMENSIONS = DIMENSIONS[:-1]
# The agent under agents/ that runs each seat: it starts without CLAUDE.md, so a seat holds only what its prompt and its reads give it.
# The agent under agents/ that runs each seat.
SEAT_AGENT = "comprehension-seat"
VALUE_NAMES = ("language", "kind", "domain", "domain docs", "3am question")
# The files no seat may open, by the setting that places each, and what each is.
+8 -9
View File
@@ -23,13 +23,13 @@ Hold all of these or the comparison doesn't prove anything.
one. Seats that read different amounts produce numbers nothing can compare.
- **Blind.** Deny the project's own conclusions — the plan, a decision log, prior review
output — and never show a panelist the metric under test. An anchored reader is a wasted one.
- **Check what the harness pre-loads, before launching.** The scoring run and the paired ruling
launch every seat as the `comprehension-seat` agent, which starts without `CLAUDE.md`, so nothing
is pre-loaded. Any other launch: `CLAUDE.md` may hold only `@AGENTS.md`, and an `@file` import
lands in a subagent's context ahead of its first tool call. That is harmless for a reader who was
going to read the charter anyway, and fatal to the architects' README-and-tree-only step. Resolve
the project's imports, name every pre-loaded file in the architects' brief, and require them to
mark each map entry that file could have fed.
- **Check what the harness pre-loads, before launching.** `CLAUDE.md` may hold only
`@AGENTS.md`, and an `@file` import lands in a subagent's context ahead of its first tool call.
That is harmless for a reader who was going to read the charter anyway, and fatal to the
architects' README-and-tree-only step. Launch each seat as the `comprehension-seat` agent, which
starts without `CLAUDE.md`, so no import is pre-loaded. For any other launch, resolve the
project's imports, name every pre-loaded file in the architects' brief, and require them to mark
each map entry that file could have fed.
- **Isolated and read-only.** Launch each with `isolation: "worktree"`, and forbid edits, test
runs and builds. Entering a worktree yourself mid-run strands a non-isolated subagent.
- **Parallel.** Launch them in one message. Nine agents reading a few thousand lines is minutes,
@@ -97,8 +97,7 @@ A scoring run needs four seats — Junior A, Mid A, the maintainability senior a
architect — plus the calibration seat ("The score") when more than one project is in play. `~/.claude/bin/larv-review prepare-scoring`
builds the four seats' prompts from `seat-prompts.md`, filled in from the project's `AGENTS.md` →
"Scoring run". Change neither between runs, or the scores are not comparable. A project without that
section gets it at its first scoring run or paired ruling. Each seat runs as the `comprehension-seat`
agent under `agents/`, which starts without `CLAUDE.md`.
section gets it at its first scoring run or paired ruling.
## The paired ruling
+1 -1
View File
@@ -1,6 +1,6 @@
# The comprehension seats' prompts
A scoring-run seat's prompt is the opening, the seat's background, the shared brief, and the report for its kind of seat, in that order. Launch each seat as the `comprehension-seat` agent, `agents/comprehension-seat.md`, which starts without `CLAUDE.md` and the rule files, so a seat holds only what its prompt and its reads give it. Copy the text verbatim and replace each `{placeholder}`:
A scoring-run seat's prompt is the opening, the seat's background, the shared brief, and the report for its kind of seat, in that order. Copy the text verbatim and replace each `{placeholder}`:
- `{checkout}` and `{branch}`: the worktree the seats read, and its branch.
- `{main}`: the project's main checkout.
+2 -2
View File
@@ -145,7 +145,7 @@ Launch one principles-auditor on the trigger in §3, so the project is read once
### Comprehension check
The comprehension check records how hard the project is for its contributor to read (`~/.claude/rules/goals-and-audience.md`), and no score blocks a merge; only a run the plan calls and the branch lacks does, per "Scoring run". Simulated readers, the seats, launched per `~/.claude/skills/comprehension-panel/SKILL.md`, each read the whole project, not the diff. It reports no findings and is no pass: it runs in §5, after every pass is done, the auto-reviewer included, so it reads the branch as review left it. It runs a paired ruling in the release review, even where an opt-out skips its architect, and a scoring run where one is due. It skips only as "Opt-out" or "Suspended" below says.
The comprehension check records how hard the project is for its contributor to read (`~/.claude/rules/goals-and-audience.md`), and no score blocks a merge; only a run the plan calls and the branch lacks does, per "Scoring run". Simulated readers, the seats, launched per `~/.claude/skills/comprehension-panel/SKILL.md` as the `comprehension-seat` agent, each read the whole project, not the diff. It reports no findings and is no pass: it runs in §5, after every pass is done, the auto-reviewer included, so it reads the branch as review left it. It runs a paired ruling in the release review, even where an opt-out skips its architect, and a scoring run where one is due. It skips only as "Opt-out" or "Suspended" below says.
**Paired ruling.** Each seat votes whether the project reads better, the same or worse at this branch's head than at the base.
@@ -155,7 +155,7 @@ The comprehension check records how hard the project is for its contributor to r
**Scoring run**, when `~/.claude/bin/larv-review needs-scoring-run <the IDs of the items the chunk ships, if any>` prints `Scoring run due:`. `chunk-pr merge` refuses until the branch's committed history records every run the plan calls, which `larv-review scoring-run-owed` counts at merge time from the merge base; an earlier due line is only a snapshot.
- **Seats.** Junior A, Mid A, the maintainability senior and the inherited architect each score the project at the head from 1 to 10 overall and on four dimensions: Navigation, Locality, Shape and Self-sufficiency. Run `~/.claude/bin/larv-review prepare-scoring`. It makes the worktree the seats read and prints each seat's prompt file; launch each seat as the `comprehension-seat` agent, with its file's text as its prompt. The paired ruling's seats are launched as that agent too. Write their lines into a scores file and run `~/.claude/bin/larv-review record-scoring <scores file> <the same item IDs>`, which appends the run to the history and prints the four seats' means.
- **Seats.** Junior A, Mid A, the maintainability senior and the inherited architect each score the project at the head from 1 to 10 overall and on four dimensions: Navigation, Locality, Shape and Self-sufficiency. Run `~/.claude/bin/larv-review prepare-scoring`. It makes the worktree the seats read and prints each seat's prompt file; launch each seat with its file's text as its prompt. Write their lines into a scores file and run `~/.claude/bin/larv-review record-scoring <scores file> <the same item IDs>`, which appends the run to the history and prints the four seats' means.
- **Floor item.** Where `record-scoring` prints `Floor:`, a `Next:` line follows: file one floor item, or refresh the open one. A floor item is a plan item meant to bring every mean to the project's readability floor, which `record-scoring`'s `Floor:` line names. File it as one ambitious refactor, not touch-ups. It restructures the area behind the places `larv-review places` prints for this run, chosen where they bear on the lowest dimension, sized to bring every mean to that floor, and quotes those places. Its tagline opens with `Reach the comprehension floor:`, so its own chunk runs a scoring run; while a mean stays under the floor, that run's `Next:` line asks for the next floor item. Mark it `owner`, since the human asked that such a project always hold one, so no score deletes it. Put it in the earliest release the plan names after the one the chunk ships into, or else in the next version after that one that `~/.claude/rules/todo-items.md` allows, so the floor doesn't hold up any release. While one is open, refresh its places and aim from the newest run instead of filing another; the item the chunk ships doesn't count as open. Commit it with the run, as "Record" says.
- **Second run.** Where `needs-scoring-run` printed that the chunk `leaves release … with no plan item`, run `prepare-scoring` again and launch the same four seats afresh on the same head. Their scores file's first line is `<PR or branch> rerun at <commit>`. Record it with the same `record-scoring` command.
- **Agreement.** After the second run, run `~/.claude/bin/larv-review agreement` and put its counts in the summary. On `Assumption fails:`, ask the user whether to keep the paired ruling or change the decision `review: the comprehension check records …`. Record the answer as a decision in the repo whose history was counted, with the counts that led to the ask. A later run asks again only when the rulings' rate falls, or the runs' rate rises, against the recorded counts.