Content
73%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 delivers an exceptionally clear four-phase debugging workflow with strong validation checkpoints, feedback loops, and real one-level-deep reference files. Its main weakness is token efficiency: roughly a third of the content repetitively enforces the same "root cause first" message across three overlapping sections, and two reference files lack in-context pointers.
Suggestions
Collapse the "Red Flags", "Common Rationalizations", and "your human partner's Signals" sections into a single compact table — they all restate the same no-fix-without-root-cause enforcement, which would cut ~60 lines without losing guidance.
Add in-context pointers to defense-in-depth.md and condition-based-waiting.md at the phases where they apply (e.g., after Phase 4 fix verification, and during waiting/retry scenarios) rather than only listing them at the end.
Move the domain-specific multi-layer codesign example into a reference file (e.g., references/instrumentation-example.md) and keep only the generic boundary-instrumentation checklist inline.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The four-phase core is dense and instructional, but the body pads the same enforcement message across three redundant sections — "Red Flags", "Common Rationalizations", and "your human partner's Signals" all restate "no fixes without root cause" — plus filler like "Violating the letter of this process is violating the spirit of debugging." This fits the mostly-efficient-but-could-be-tightened anchor; it is not the severely-verbose anchor at 1 because nothing explains concepts Claude already knows, and not 4 because the redundancy is substantial, not minor. | 3 / 5 |
Actionability | Concrete guidance includes a copy-paste bash instrumentation example for multi-component systems, an explicit numeric decision rule ("If ≥ 3: STOP and question the architecture"), a failing-test gate, and pointers to real scripts like find-polluter.sh. It stops short of 5 because some directives remain abstract ("Trace Data Flow", "Find Working Examples") without concrete techniques for the non-referenced phases, and the inline example is domain-specific (macOS codesign) rather than covering common cases. | 4 / 5 |
Workflow Clarity | The four phases are strictly sequenced with "You MUST complete each phase before proceeding to the next", each phase has numbered sub-steps, a Quick Reference table gives success criteria per phase, and there is an explicit feedback loop: verify fix → if failed and <3 attempts return to Phase 1 → if ≥3 attempts stop and question architecture with the human partner. This matches the clear-sequence-with-explicit-validation-and-feedback-loops anchor. | 5 / 5 |
Progressive Disclosure | All three referenced files (root-cause-tracing.md, defense-in-depth.md, condition-based-waiting.md) exist, are one level deep, and are clearly listed with one-line descriptions in Supporting Techniques; root-cause-tracing is also signaled at point of use in Phase 1. It falls short of 5 because defense-in-depth and condition-based-waiting have no in-context pointers where they would apply, and the long inline codesign instrumentation example could itself live in a reference file. | 4 / 5 |
Total | 16 / 20 Passed |