Content
77%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A well-structured, human-in-the-loop forensic workflow: the 8-step guided flow has explicit validation checkpoints and failure handling, and progressive disclosure is exemplary — every referenced bundle file exists, is one level deep, and is purpose-labeled. The main weakness is repetition: the same safety rules and motivational framing appear three to four times across the philosophy section, the steps, the output contract, and the Hard nevers.
Suggestions
State the never-write-main / never-auto-merge rule once (e.g., in Hard nevers) and reference it from S5, Step 6, and the output contract instead of restating it four times — the repetition is the largest token cost in the body.
Trim the motivational framing ("The bigger picture — say it to the human, because it's the point", the flywheel-is-the-point passages) to one short line; the framing reappears in references/evals.md, so paying for it twice is pure overhead.
Consider collapsing the S1–S9 philosophy list into the steps that use them (most already carry the S-tag) or moving the full list to a reference file, keeping only the routing table (S9) inline since it's the one consulted mid-flow.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient, dense, project-specific guidance Claude cannot infer (the PR-comment session contract, the four routing destinations, the branch-landing procedure) — but the same rules are restated multiple times: "Never write `main`" appears in S5, Step 6 ("Never write `main`; never auto-merge"), the output contract ("never on `main`"), and "Hard nevers", and motivational framing ("say it to the human, because it's the point", "This is the flywheel...") pads without instructing. This fits the score-3 anchor 'mostly efficient but includes some unnecessary explanation or could be tightened' — more repetition than the score-4 'minor instances', but the bulk is genuinely non-inferable knowledge, so not the score-2 'several unnecessary explanations'. | 3 / 5 |
Actionability | The flow gives concrete, executable guidance: "Run `scripts/resolve-sessions.sh <PR#|feature>`", the `~/.claude/projects/*/<id>.jsonl` glob, "Detached-checkout the PR head, commit the eval/context changes, `git push origin HEAD:<branch>`", and "branch `capture/<slug>` off `origin/main`". Not a 5 because some execution detail is prose-delegated to references ("with exact git commands" in outcomes.md) rather than inline copy-paste-ready commands; not a 3 because the guidance is genuinely executable, not high-level hints or pseudocode. | 4 / 5 |
Workflow Clarity | Steps 0–7 are explicitly sequenced with checkpoints at every risky point: preflight ("Confirm the working tree is clean; if there's WIP, ask the user to stash or commit first"), an explicit failure path (the script "flagging any whose file is missing (a remote/CI run — see the degradation note)"), human validation before analysis ("Tell the human your triage in two lines before diving"), and human confirmation before any write ("Confirm the human's explicit choice"), plus a "Hard nevers" checklist and a final restore step ("`git checkout main` so the user ends where they started"). This matches the score-5 anchor: clear sequence, explicit validation, error recovery, and a checklist. | 5 / 5 |
Progressive Disclosure | The body is an overview that splits detail into four real, one-level-deep references, each signaled with its purpose and a hackable-seam note ("`references/trace-reading.md` — where session IDs come from (the PR comment), how to locate and read the local JSONL traces, the triage map, and the four reading lenses"), plus one script; all five bundle files exist and are substantive. This matches the score-5 'clear overview with well-signaled one-level-deep references; content appropriately split' anchor — no nesting, no buried references, no detail that belongs in a file left inline. | 5 / 5 |
Total | 17 / 20 Passed |