Content
75%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, highly actionable process skill: concrete git commands, literal sub-agent prompt briefs, a fail-fast validation checkpoint, and explicit handling of missing inputs. All four dimensions land at 4 due to small, consistent gaps — an inlined smell baseline, dangling references to a tracker doc and a setup skill with no paths, and no retry guidance for failed sub-agent outputs.
Suggestions
Move the 12-smell baseline (step 3) into a references/ file (e.g. references/smell-baseline.md) and have the orchestrating agent read and paste it when spawning the Standards sub-agent — this trims ~20 lines from SKILL.md (conciseness) and improves progressive disclosure while preserving the paste-into-prompt behavior.
Replace the dangling "the tracker doc" and "/setup-matt-pocock-skills" references with concrete paths or the actual command to run, so the spec-fetch workflow is executable without guessing (actionability).
Add a brief retry/re-prompt instruction for when a sub-agent report is malformed, over the word limit, or the spec fetch fails, giving the workflow an explicit feedback loop (workflow clarity).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body assumes Claude's competence — code smells are given as terse name → fix one-liners and nothing basic is explained — but there is minor redundancy ("Start every sub-agent with a fresh context window" repeats "so they don't pollute each other's context") and the ~20-line smell baseline is inlined when it could live in a reference file. This matches anchor 4 (efficient, minor trimming possible) rather than anchor 5's every-token-earns-its-place leanness. | 4 / 5 |
Actionability | Concrete, executable guidance throughout: "git diff <fixed-point>...HEAD", "git log <fixed-point>..HEAD --oneline", "git rev-parse <fixed-point>", plus two literal quote-ready sub-agent briefs and an ordered spec-source lookup with fallbacks. It falls short of anchor 5 only because of dangling pointers — "fetched via the workflow in the tracker doc" and "/setup-matt-pocock-skills" have no path or in-bundle target — matching anchor 4 (mostly executable, minor gaps). | 4 / 5 |
Workflow Clarity | A clear five-step sequence with an explicit fail-fast validation checkpoint ("confirm the fixed point resolves... A bad ref or empty diff should fail here, not inside two parallel sub-agents") and error branches (no fixed point → ask; no spec → skip and note). It matches anchor 4 rather than 5 because there is no retry/re-prompt feedback loop for outcomes like a malformed sub-agent report or a failed spec fetch. The destructive/batch cap does not apply since this is a read-only review skill. | 4 / 5 |
Progressive Disclosure | No bundle files exist, and the body is well organized into a numbered process with clear headings and a rationale section, so navigation is easy. It sits at anchor 4 rather than 5 because at ~85 lines the 12-smell baseline is inlined where a references/ file could hold it, and external references ("the tracker doc", "/setup-matt-pocock-skills") are not clearly signaled with paths; it is well above anchor 3's muddled organization. | 4 / 5 |
Total | 16 / 20 Passed |