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 lean, well-sequenced procedural contract with explicit validation, a blocked-result feedback path, a verification checklist, and exemplary one-level progressive disclosure to the ADR template. Its main weakness is repetition — the immutability and boundary constraints are restated across several sections, inflating token cost without adding information.
Suggestions
Consolidate the immutability rule — currently stated in step 2, step 5, and Boundaries — into one authoritative statement to reduce token cost.
Trim the Boundaries section of items already enforced inline in the workflow steps (e.g., one ADR per request, not creating directories) and keep only genuinely new constraints.
Add one concrete example of a `written` result object (field names and sample values) so the return contract is unambiguous without interpretation.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly efficient procedural rules with no background explanations of concepts Claude already knows, but it includes repeated restatements: the immutability rule appears in step 2 ("Existing ADRs are immutable regardless of status"), step 5 ("no existing ADR was modified"), and Boundaries ("Modify application code, tests, plans, current-state context, or existing ADRs"); allowed statuses are listed in both step 1 and step 2; and the Boundaries section largely repeats constraints already enforced in the workflow steps (one ADR per request, no directory creation). This fits anchor 3 — mostly efficient but could be tightened — rather than anchor 4, since the redundancy spans several sections rather than being minor. | 3 / 5 |
Actionability | Guidance is concrete throughout: the exact path pattern "context/decisions/YYYY-MM-DD-<decision-slug>.md", the exact allowed status list ("Proposed, Accepted, Rejected, Deprecated, Superseded"), explicit result field lists ("status, adr_path, decision, decision_status, created, supersedes, verification"), and a real referenced template. It falls short of anchor 5 only because no concrete example of a `written` or `blocked` result payload is given, leaving the return contract described but not exemplified. | 4 / 5 |
Workflow Clarity | Six explicitly numbered steps with input validation at step 1 ("Confirm the request contains exactly one decision, qualifying evidence..."), a blocked error path carrying "the specific problem, its impact, and the required_action" as a recovery feedback mechanism, and an explicit verification checklist at step 5 ("exactly one ADR was created or one existing matching ADR was reused... no existing ADR was modified"). This matches anchor 5: clear sequence, explicit validation steps, and error-recovery guidance. | 5 / 5 |
Progressive Disclosure | The body is cleanly sectioned (Purpose, Input, Qualification handoff, Workflow, Boundaries) and defers the ADR schema to a real, verified one-level reference: "Read references/adr-template.md before writing. It is the sole authority for the persisted ADR schema", explicitly instructing "do not restate or invent a parallel section contract here". The bundle contains exactly that one reference file, appropriately split and clearly signaled, matching anchor 5. | 5 / 5 |
Total | 17 / 20 Passed |