Content
70%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.
The body presents a coherent, well-validated pipeline: deterministic evidence retrieval, adversarial judgment, an alignment loop with a monotonic-improvement guard, and a ship gate. Its two real weaknesses are redundancy (the deterministic-Stage-2 rationale and sibling-boundary rules are each restated multiple times) and unshipped dependencies — the evals/ files cited in the ship gate and both out-of-bundle persona links do not exist in the bundle. Tightening the repetition and making every referenced path resolve would lift the content from good to excellent.
Suggestions
State the deterministic-Stage-2 rationale and the sibling-boundary rules once each (Architecture and Sibling contract respectively) and drop their restatements in 'Failure modes guarded against' and 'When NOT to activate' — this alone removes roughly a quarter of the body's tokens.
Ship the referenced evals/ files (trigger-evals.json, content-evals.json, run-evals.sh) or remove them from 'Ship gate' and 'Bundled assets' — the ship gate currently instructs running an eval-runner that is not in the bundle.
Replace the out-of-bundle ../../personas/*.persona.md links with in-bundle paths or inline the persona requirements, so every path a reader can follow actually resolves.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Quotes: 'Stage 2 is the load-bearing design choice: evidence retrieval is DETERMINISTIC (grep + AST hints), not LLM... it cannot hallucinate support that the retriever did not find' reappears almost verbatim in Failure modes as 'Stage 2 is deterministic; judge sees only real evidence'. The sibling boundary is also stated four times (description-level routing, the Sibling contract table, 'When NOT to activate', and 'Dispatch collision' in Failure modes). Mostly efficient with no basic-concept padding, but the repeated design rationale and boundary restatements go beyond 'minor instances of over-explanation' (anchor 4) — the body could lose ~20-25% of its tokens without information loss, which is the anchor-3 case. | 3 / 5 |
Actionability | Quotes: 'script: scripts/extract-claims.py', 'pipe to scripts/retrieve-evidence.sh', 'assets/judge-prompt.md -- Stage 3 adversarial judge prompt', with concrete JSON I/O shapes ('{"page", "claims":[{"id","text","section","keywords","expected_source_areas"}]}'). All three scripts and the judge prompt exist in the bundle and behave as described (verified: extract-claims.py emits prompts and a schema, retrieve-evidence.sh is pure ripgrep, verify-page.sh orchestrates). Not 5 because no end-to-end example invocation is shown, and the ship-gate instruction 'The eval-runner (see evals/) passes on the trigger evals' points at files (evals/run-evals.sh, trigger-evals.json, content-evals.json) that are absent from the bundle, so that step cannot actually be executed as written. Not 3 because the core pipeline guidance is executable, not pseudocode. | 4 / 5 |
Workflow Clarity | Quotes: a six-phase pipeline (SCOPE -> EXTRACT -> RETRIEVE -> JUDGE -> SYNTHESIZE -> ALIGNMENT LOOP) with per-phase inputs and outputs; 'RE-RUN the pipeline on the same pages. The grounding_rate must MONOTONICALLY INCREASE between iterations or the loop has diverged -- stop and escalate'; UNSUPPORTED retry logic ('if retrieval_fix_suggestion is plausible, retry retrieval with the suggested keywords'); and a ship gate ('grounding_rate >= 0.9 on each verified page', 'Every CONTRADICTED claim cited a specific code file:line'). This is a batch operation that DOES have explicit validation steps, an error-recovery feedback loop, and a completion checklist — the anchor-5 pattern, so the batch-operation cap does not apply. | 5 / 5 |
Progressive Disclosure | The body keeps a proper overview-to-bundle split and signals references clearly ('Bundled assets' section with per-file descriptions; scripts/ and assets/judge-prompt.md all exist one level deep). However, scoring against the actual bundle: 5 of the 9 referenced paths are phantom — 'evals/trigger-evals.json', 'evals/content-evals.json', 'evals/run-evals.sh' (no evals/ directory ships), and '[python-architect persona](../../personas/python-architect.persona.md)' / '[doc-writer persona](../../personas/doc-writer.persona.md)' (no personas directory exists at that relative path). Missing referenced files are more than 'minor organization gaps' (anchor 4), placing this in anchor 3 territory despite otherwise good structure. | 3 / 5 |
Total | 15 / 20 Passed |