Content
86%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 instruction skill: an unambiguous single-pass workflow, concrete per-bucket actions, and exemplary one-level-deep reference splitting that keeps commands and taxonomy out of the narrative. The main costs are a redundant 'Hard nevers' restatement and a missing explicit verify-before-push checkpoint on Clear fixes.
Suggestions
Cut or compress the 'Hard nevers' section: seven of its eight bullets restate rules already given in the one-way model, skip-rule, scope-tight, and idempotency sections — either drop it or keep only the two rules not stated elsewhere (never act on human comments is already in the one-way model; the truly novel ones are minimal).
Add an explicit validation checkpoint for Clear fixes: before commit/push, re-run the project's checks (e.g., scripts/local-checks.sh or prds/<f>/run-prd-test.sh) so the pushed diff is verified, not just scoped — this closes the workflow_clarity gap without adding a round.
Trim the dispatcher-contract repetition: the 'Idempotent' bullet and round-counter text overlap the Idempotency section and the one-way model; one statement of each would save ~8 lines.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly lean, load-bearing instruction with no explanation of concepts Claude already knows — the enumerated suppression directives ("eslint-disable*, @ts-ignore / @ts-expect-error, # type: ignore ... # noqa") and skip markers are pure project-specific rules, not padding. It stops short of the 5 anchor because the 'Hard nevers' section restates ~90% of rules already given in the one-way model, skip-rule, and idempotency sections, and the 'Contract with the dispatcher' section re-covers idempotency — trimmable redundancy rather than the 'every token earns its place' ideal. | 4 / 5 |
Actionability | As an instruction-only skill the guidance is fully actionable: exact paths ("prds/<f>/run-prd-test.sh", ".harness/feedback-rounds-<f>", ".claude/skills/expert/references/*.md"), the four-bucket decision table with an exact action per bucket, and the copy-paste-ready gh/git/GraphQL commands in references/gh-mechanics.md, which the body points to by exact path. Per the code_vs_instruction note, absence of inline code is not penalized when guidance is this concrete; the common cases (fix-and-push, reply-in-thread) each have specific executable steps. | 5 / 5 |
Workflow Clarity | A clear four-step sequence (re-derive state → triage → act per bucket → exit) with genuine checkpoints: idempotency re-derivation from ground truth before acting, PRD/Expert grounding before classifying, and the scope-tight/never-silence constraints on every Clear fix. It misses the 5 anchor because there is no explicit verify-the-fix checkpoint before push (e.g., re-run local checks or the PRD test) — the only verification is the stated precondition that the feature already worked. Not capped at 3: this is not a destructive operation and state validation (both idempotency checks) is present and explicit. | 4 / 5 |
Progressive Disclosure | The body is a genuine overview and the split is deliberate and clean: the fiddly plumbing commands live in references/gh-mechanics.md and the classification taxonomy with worked examples in references/triage.md — both real files (verified), one level deep, each signaled by exact path at its point of use ("see references/gh-mechanics.md for the exact commands", "The taxonomy, boundary heuristics, and examples live in references/triage.md — read it"). No detail that belongs in a reference is inlined; navigation is trivial. Matches the 5 anchor. | 5 / 5 |
Total | 18 / 20 Passed |