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 is highly actionable with a clear, well-validated workflow — commands are copy-paste ready and verification/feedback loops are explicit. Its weaknesses are verbosity (duplicated pattern catalog, generic pytest/pdb/git reference material Claude already knows) and inlining content that belongs in the existing references/failure-patterns.md bundle file.
Suggestions
Remove Section 4's inlined pattern catalog and Section 2's error-type indicators where they duplicate references/failure-patterns.md; keep one-line pointers to the reference file instead.
Delete or trim 'Common Investigation Commands' and 'Tips for Effective Analysis' — pytest flags, pdb usage, and basic git commands are knowledge Claude already has.
Move the full report template into a reference file (e.g., references/report-template.md) and keep only a brief outline of required sections in the body.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Noticeably verbose across several padded sections: 'Common Investigation Commands' restates pytest flags (-vv, -s, -x, --lf, --durations) and pdb/git basics Claude already knows, 'Tips for Effective Analysis' is generic advice ('Git history is your friend', 'Don't assume—test your hypotheses'), and Section 4 inlines a pattern catalog (API Signature Change, Return Type Change) that duplicates references/failure-patterns.md. Not 1 because much of the content (bisect workflow, report format, likelihood ranking) is genuinely non-obvious and useful; not 3 because the duplication and known-material padding spans multiple sections of a ~550-line body. | 2 / 5 |
Actionability | Fully executable throughout: copy-paste git bisect sequences, git log -S searches, pytest invocations, fixture/mock debugging snippets, a complete report template with evidence and likelihood fields, and three worked example workflows. Not 4: the examples are concrete and copy-paste ready, covering the common cases (signature change, flaky test, dependency update) rather than leaving minor gaps. | 5 / 5 |
Workflow Clarity | Six clearly sequenced steps (gather info → analyze errors → identify changes → match patterns → report → verify) with an explicit validation step and an error-recovery feedback loop: 'If fix doesn't work: 1. Review alternative hypotheses 2. Gather more information 3. Expand investigation'. The report template also mandates alternative hypotheses with likelihoods. Not 4: verification checkpoints and the retry-on-failure loop are explicitly stated, matching the top anchor; no destructive/batch cap applies since this is read-only investigation. | 5 / 5 |
Progressive Disclosure | The reference file exists and is clearly signaled twice ('See [failure-patterns.md](references/failure-patterns.md)'), but the body inlines a four-pattern catalog that substantially duplicates the bundle file's content, and the full report template is embedded inline within step 5. Not 2 because references are clearly signaled and the body has real section structure; not 4 because content that clearly belongs in the separate file is duplicated in the body instead of deferred to it. | 3 / 5 |
Total | 15 / 20 Passed |