Content
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The methodology is clearly sequenced with strong validation checkpoints and concrete, actionable guidance including a copy-paste exit template. The main weaknesses are mild redundancy between the cycle and the failure-modes section, and a broken reference to a missing worked-example file.
Suggestions
Create the referenced examples/headless-bg-agent-empty-stdout.md (or remove the dead reference) so progressive disclosure works as advertised.
Trim or fold the 'Failure Modes to Avoid' section into the relevant cycle steps to remove redundancy with steps already stated.
Move the worked examples and possibly the failure-mode detail into a separate referenced file to shorten the main body and improve progressive disclosure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly efficient and useful, but the opening paragraph and the 'Failure Modes to Avoid' section partly restate themes already covered in the cycle, and some general debugging philosophy ('the natural instinct is to form a theory and immediately apply a fix') is padding Claude already knows. | 2 / 3 |
Actionability | Although it is instruction-only with no executable code, the guidance is concrete and specific: 'identify the 2-3 places where your hypothesis makes a testable prediction', 'Prefer logging values over presence checks', a list of common instrumentation traps, and a copy-paste exit template ('Root cause: ... Evidence: ... Fix: ...'). | 3 / 3 |
Workflow Clarity | The 6-step cycle (Hypothesize, Design Instrumentation, Verify Data Collection, Run and Observe, Document Findings, Iterate) is clearly sequenced with explicit validation checkpoints ('believe the data', 'A test run that produces no data is wasted'), a 3-round escalation rule, and an exit checklist. | 3 / 3 |
Progressive Disclosure | The body is well-organized into clear sections, but it is a ~190-line monolithic file with no bundle files split out, and its only external reference ('examples/headless-bg-agent-empty-stdout.md') points to a file that does not exist, so the reference is broken. | 2 / 3 |
Total | 10 / 12 Passed |