Content
81%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.
An exceptionally actionable, well-sequenced orchestration procedure with real validation checkpoints and error-recovery loops at every phase, and a clean two-file reference split. Its main weakness is density: ~450 lines of repetitive legalistic prose where several trust-boundary and private-material rules are restated multiple times and could be consolidated.
Suggestions
Consolidate the repeated untrusted-code and sandbox-ownership rules (currently stated in the Trust boundary, section 4, and section 5) into a single authoritative statement, cross-referencing it from later sections.
Move the detailed adjudication heuristics and close-without-merge evidence rules into references/review-policy.md, keeping the body focused on orchestration order and command sequences.
Mention scripts/snapshot.mjs where snapshot behavior is described (or note that reviewctl.mjs invokes it) so every bundle file is accounted for in the body.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body never explains concepts Claude already knows and nearly every sentence is task-specific policy, but it is ~450 lines of dense, legalistic prose with noticeable repetition: untrusted-code execution rules appear in the Trust boundary, the section 4 dispatch instructions, and twice in section 5; private-material handling rules in section 2 ("never quote, paraphrase, attribute, or allude to private content") reappear in section 6; and sandbox ownership rules are stated in both the Trust boundary and section 5. This is more than the "minor instances" of the 4 anchor — the document could be meaningfully tightened by deduplication — but there is no generic padding, so it sits above the 2 anchor. | 3 / 5 |
Actionability | Guidance is fully executable: exact copy-paste commands with argument placeholders for every phase ("node .agents/skills/review-pr/scripts/reviewctl.mjs begin --pr <PR_NUMBER_OR_URL>", verify-evidence, sandbox-up, finalize, abort, polygraph-context), the sandbox exec pattern "tools/review-sandbox/sandbox exec <SANDBOX> -- bash -s < <HEAD_SCRIPT>", and a concrete dispatch input block naming every artifact path. Common cases (success, retry, abort, recovery, denied approval) are each covered with specific steps. | 5 / 5 |
Workflow Clarity | The seven numbered sections give a clear sequence (Preflight → Freeze → Close-check → Charter → Dispatch → Runtime checks → Adjudicate → Finalize/Abort), and validation checkpoints with feedback loops are pervasive: verify-evidence after each lane with one correction request then abort on retry failure, finalize failure handled by "correct the input or environment and rerun", an explicit cybersecurity-interruption recovery procedure, and a defined abort path with a reason file. This matches the 5 anchor (explicit validation, error-recovery feedback loops) and clearly exceeds the 4 anchor. | 5 / 5 |
Progressive Disclosure | The bundle structure is good: both references (review-policy.md, output-contract.md) are real files, clearly signaled with an imperative read-first instruction, and exactly one level deep; scripts are invoked by path throughout. It falls short of the 5 anchor because the body itself retains substantial inline policy detail — adjudication rules, close-without-merge heuristics, sandbox lifecycle minutiae — that could partly live in the policy reference, and scripts/snapshot.mjs is present in the bundle but never referenced from the body, leaving a minor organization gap. | 4 / 5 |
Total | 17 / 20 Passed |