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.
A disciplined, well-sequenced debugging methodology with strong validation checkpoints and a concrete exit template — its workflow clarity is exemplary. Weaknesses are repetition of the data-vs-code-paths theme across sections and a worked-example reference that points to a nonexistent file.
Suggestions
Add the missing 'examples/headless-bg-agent-empty-stdout.md' file (or remove the 'Worked examples' section) so the body's only external reference resolves.
Consolidate the three separate statements of 'instrument data, not code paths' (step 2, the failure-modes section, and 'Persistent State') into one authoritative section to cut roughly 20-30 lines.
Fix the typo 'does does it hang or exit cleanly?' and turn the environment-diff catalogue in 'Reframing the user's report' into a concrete checklist (TTY vs pipe, locale, env vars, prior state).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly efficient — the good/bad hypothesis example, the instrumentation traps list, and the exit-criteria template all earn their tokens — but themes repeat: 'instrument data, not code paths' appears in step 2, again as a failure mode, and again in 'Persistent State'; 'blaming external systems' appears in the description-echo and its own section. This matches anchor 3 ('mostly efficient but includes some unnecessary explanation or could be tightened'); it is not a 2 because there is no padding explaining concepts Claude already knows, and not a 4 because consolidating the repeated data-vs-code-paths material would meaningfully shrink the file. | 3 / 5 |
Actionability | The guidance is concrete and executable for an instruction-only skill: a worked good/bad hypothesis pair, the 2-3 instrumentation points rule with a self-check question, an enumerated list of data-capture traps, and a copy-ready exit template ('Root cause: [specific mechanism] / Evidence: [specific log lines] / Fix: ...'). Per the rubric's scoring notes, absence of code is not penalized when guidance is actionable; it is not a 5 because some directives remain abstract ('catalogue what differs between their environment and yours' has no checklist or example) and there is a typo ('does does it hang'). | 4 / 5 |
Workflow Clarity | The six-step cycle (Hypothesize → Design Instrumentation → Verify Data Collection → Run and Observe → Document Findings → Iterate) is clearly sequenced with explicit validation checkpoints: step 3 exists solely to verify data capture, step 4 mandates believing data over theory ('When the data contradicts your hypothesis, believe the data'), and the exit section requires evidence-backed root-cause confirmation before any fix, with a re-verify clean run after applying it. There is also an escalation checkpoint ('If you're not making progress after 3 rounds, step back and question your assumptions'). This matches anchor 5's explicit validation steps, feedback loops, and checklists; it is clearly above anchor 4's 'minor validation gaps'. | 5 / 5 |
Progressive Disclosure | Section structure is good (numbered cycle, failure modes, exit criteria), but the single external reference — 'examples/headless-bg-agent-empty-stdout.md' — points to a file that does not exist in the bundle (no examples/, references/, scripts/, or assets/ directories are present). A clearly signaled but broken reference means navigation fails at exactly the point a reader would follow it, fitting anchor 3 ('some structure but could be better organized; references present but not clearly signaled' — here, not usable). It is not a 2 because the body is not an inlined wall of text that belongs in separate files, and not a 4 because a dead link is more than a minor organization gap. | 3 / 5 |
Total | 15 / 20 Passed |