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.
A well-structured process skill: the four-phase workflow is clearly gated with explicit validation and feedback loops, and bundle references are properly organized one level deep with verified paths. Its main weakness is redundancy — four separate sections restate the phase rules — plus some abstract directives and an inline example that belong in references.
Suggestions
Consolidate 'Red Flags', 'Common Rationalizations', and "your human partner's Signals" into a single compact table or fold them into their relevant phases — the 3+-fixes architecture rule alone is currently stated in four places.
Replace abstract directives like 'Research more', 'Ask for help', and 'Gather more data, don't guess' with concrete next actions (e.g., specific commands to run or what evidence to collect next).
Move the ~30-line multi-layer bash instrumentation example into a reference file (e.g., references/evidence-gathering.md), keeping only a 2-3 line pointer and summary inline, consistent with how Phase 1.5 handles root-cause-tracing.md.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The four-phase core is efficiently written, but four sections — 'Red Flags', 'Common Rationalizations', "your human partner's Signals", and the 'Quick Reference' table — largely restate the same rules already stated in the phases (e.g., the 3+-fixes architecture rule appears in Phase 4, Red Flags, and the Rationalizations table). Fits 'Mostly efficient but includes some unnecessary explanation or could be tightened': not 4 because roughly 40% of the body is restatement that could be cut, not 2 because the padding is self-reinforcement of its own process rather than explanation of concepts Claude already knows. | 3 / 5 |
Actionability | Provides mostly executable guidance: a concrete copy-paste bash instrumentation example for multi-layer evidence gathering, explicit thresholds ('If ≥ 3: STOP and question the architecture'), a failing-test-first directive, and pointers to sibling skills and reference files. Not 5 because several directives remain abstract ('Research more', 'Ask for help', 'Gather more data, don't guess') and the Phase 1.4 evidence block is pseudocode; not 3 because the guidance is specific and executable across the common cases. | 4 / 5 |
Workflow Clarity | Four phases are clearly sequenced with hard gating ('You MUST complete each phase before proceeding to the next'), explicit validation checkpoints (failing test required before fixing, 'Test passes now? No other tests broken?'), and feedback loops for error recovery (failed hypothesis → form NEW hypothesis; 3+ failed fixes → return to Phase 1 or question architecture). Matches the anchor 'Clear sequence with explicit validation steps; feedback loops for error recovery; checklists' — the 'Quick Reference' table serves as the checklist; only a minor label inconsistency ('see Phase 4.5' vs 'step 5 below') keeps it from being flawless, but it clearly fits this anchor over the 4 anchor, which allows validation gaps. | 5 / 5 |
Progressive Disclosure | Three well-signaled one-level-deep references, all verified to exist, each with a one-line description in 'Supporting Techniques' plus inline pointers (Phase 1.5 gives a 'Quick version' then defers to references/root-cause-tracing.md); companion files (find-polluter.sh, condition-based-waiting-example.ts) are correctly nested one level further inside their parent references. Fits 'Good structure; most content is appropriately placed; references mostly clear; minor organization gaps' — not 5 because the 285-line body is a full process document rather than a lean overview, with the ~30-line inline multi-layer bash example being detail that could live in references/, mirroring how root-cause-tracing.md handles its quick version. | 4 / 5 |
Total | 16 / 20 Passed |