Content
85%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.
The body is an exceptionally lean, rule-dense contract: fully executable commands with explicit failure handling, a genuine self-validate feedback loop, and precise scoping rules for re-review and mutation-stability runs. Its weaknesses are structural rather than instructional — four referenced files are missing from the bundle, one reference file is undiscoverable from the entrypoint, and the copy/poll protocols are inlined and repeated instead of being split out.
Suggestions
Ship or fix the referenced files: workflows/review.md, workflows/codebase-review.md, workflows/qa-review.md and schemas/review-finding.md are cited from SKILL.md but absent from the bundle, breaking navigation from the entrypoint (and taking the finding-JSON contract with them).
Link references/perf-qa.md directly from SKILL.md — e.g. in the workflow table's qa-review row or a QA section — so it is discoverable without relying on the missing workflows/qa-review.md.
Extract the repeated worktree-copy/free-space protocol (§ Ethos, § Output Contract, § Mutation-Stability Pairing) and the inline waiter-poll shell one-liner into a single reference file or helper script to remove duplicated tokens from SKILL.md.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is rule-dense with zero padding and zero explanation of concepts Claude already knows ("Fewer high-conviction findings beat lists of nits", "A zero RESULT is a result"), fully assuming competence. It falls short of anchor 5 because the worktree-copy/free-space protocol is restated across § Ethos, § Output Contract and § Mutation-Stability, and the ~300-word inline waiter-poll shell one-liner (§ Mutation-Stability Pairing) is mechanical detail that could be trimmed into a script or reference. | 4 / 5 |
Actionability | Commands are complete and copy-paste ready with every flag and placeholder: `scripts/review-depth --base REF --head REF --repo DIR`, `review-artifact-check --path/--file`, `mutation-stability --worktree [WORKTREE_PATH] --sha [SHA] --test '[TEST_CMD]' ... --stability [SAMPLE_COUNT]`, plus exact shell (`git archive REV | tar -x -C "$dir"`, `mktemp -d "${TMPDIR:-/tmp}/review-copy.XXXXXX"`, `df -Pk "$dir"`), stated defaults (60s/300s budgets), and failure contracts (rerun on exit 124, exit-127 guard in the poll). Anchor 5 fits; the caller-supplied TEST_CMD/BUILD_CMD parameters are legitimately per-change, not gaps. | 5 / 5 |
Workflow Clarity | The Output Contract is an explicit sequence with a real validate-fix-retry loop — capture starting fields, write the findings JSON to the Artifact path, "Self-validate before returning ... Fix until this prints \"ok\": true\"", then return the filled `<output_format>` block — and Mutation-Stability adds bounded phases, budget/timeout rules, retry-on-124, and never-end-turn conditions. Re-review scoping is precise (Fixed items suppressed unless the defect persists; re-report verbatim with the recorded sha). Anchor 5's explicit validation steps with feedback loops are fully met, including for the batch-like copy/build/test operations. | 5 / 5 |
Progressive Disclosure | The references that exist are well-signaled and one level deep (`references/finding-disposition.md` with a clear ownership statement, `scripts/review-depth`, `scripts/mutation-stability`), but four paths cited from the body — `workflows/review.md`, `workflows/codebase-review.md`, `workflows/qa-review.md`, and `schemas/review-finding.md` — do not exist in the bundle, and `references/perf-qa.md` exists but is unreachable from SKILL.md (it is loaded only via the missing qa-review.md). This is more than anchor 4's "minor organization gaps", matching anchor 3; it is not 2 because the references that do resolve are clearly signaled and never nested. | 3 / 5 |
Total | 17 / 20 Passed |