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 tightly scoped, well-sequenced specialist skill with explicit verification and stop paths, but it pays a token tax by restating the same prohibitions in three separate sections. Moving reference material out of SKILL.md and deduplicating the never-lists would lift it further.
Suggestions
Consolidate "The one thing that matters", "You may NEVER silence a check", and "Hard nevers" into one section — the three lists overlap almost completely and cost ~20 lines for no added constraint.
Move the exhaustive suppression-directive enumeration and the dispatcher-contract details into a `references/` file, keeping SKILL.md as a lean overview with one-level-deep pointers.
Add one brief worked triage example (a real failure message → the honest fix it points at) to sharpen the needs-judgment branch, which is currently the only vague direction.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly lean and imperative with no concept re-teaching, but the core prohibitions are stated three times: "**Every one of those is forbidden**" in the opening section, the full "You may NEVER silence a check" list, and then "Hard nevers" which restates "Never silence a check", "Never add a test-skip marker", and "Never touch the check machinery" already covered above. Roughly 15–20 lines could be cut without losing a single constraint. Not 2 because there is no padding or explanation of things Claude already knows; not 4 because the duplication is more than a minor trim — it is a structural restatement of the same list. | 3 / 5 |
Actionability | Concrete commands throughout: `./scripts/local-checks.sh`, `./prds/<f>/run-prd-test.sh`, `claude -p "/fix-local-checks <feature>"`, a model commit message (`fix(local-checks): trim query whitespace`), and an exact enumeration of forbidden directives (eslint-disable*, @ts-ignore, # noqa, #[allow(...)]). Not 5 because some directions stay judgment-shaped ("Do the best **honest** fix you can", "Make whatever honest partial progress you can") without a worked example of triage in action; not 3 because everything runnable is spelled out exactly. | 4 / 5 |
Workflow Clarity | Steps 1–5 are a clear, ordered sequence with an explicit validation checkpoint ("Re-run `./scripts/local-checks.sh`" before commit), a feedback loop (dispatcher re-runs the gate; partial-progress commits so attempts compound), and a defined stop/error-recovery path (step 5, STUCK escalation). Not 4 because validation is explicit at the commit boundary and both success and failure outcomes are fully specified. | 5 / 5 |
Progressive Disclosure | Well-organized single-file skill with clear section headers and no bundle files, so nothing is mis-filed or nested; navigation is easy. Not 5 because at ~105 lines it exceeds the simple-skill (<50 lines) exception and some reference-shaped material (the exhaustive suppression-directive list, the dispatcher contract) could live in a references file with SKILL.md as overview; not 3 because the structure that is present is clean and nothing that belongs elsewhere is buried. | 4 / 5 |
Total | 16 / 20 Passed |