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 lean, opinionated, instruction-only skill whose guidance (conventions, commands, commit formats) is concrete and executable, with clear sequencing and decision branches for the audit workflow. The main defect is that the referenced audit script is not shipped in the bundle, which weakens both actionability and the audit's validation story.
Suggestions
Ship `trace-audit.bb` in the skill's `scripts/` directory — the core audit workflow and its validation checkpoints currently depend on a file the bundle does not contain.
Add an explicit re-audit step after each remediation (e.g., "after writing the missing test or marking the spec superseded, re-run `scripts/trace-audit.bb` until clean") to close the feedback loop.
Trim rationale and anecdote tokens ("instead of archaeology", the 29k-LOC port anecdote) to squeeze out the last bits of token efficiency.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and teaches only project-specific conventions Claude cannot infer (ID placement rules, commit-subject format, divergence marking), with concrete examples like `search: grep tree content (git_search_files)`. Not a 5 because a few rationale/anecdote tokens could be trimmed ("instead of archaeology", "a 29k-LOC port needed exactly 5 work-item IDs"); not a 3 because nothing explains concepts Claude already knows. | 4 / 5 |
Actionability | Gives concrete, executable guidance: `rg -n 'REQ-SALE-003' specs/ src/ tests/`, the exact comment format `// REQ-SALE-003`, and the spec naming pattern `specs/REQ-<AREA>-<NNN>.md`. Not a 5 because the core instruction "Run `scripts/trace-audit.bb` (copy it to `scripts/` in the project)" depends on a script that is not present in the skill bundle. | 4 / 5 |
Workflow Clarity | "Changing a requirement" is a clear numbered sequence with checkpoints (blast-radius search first, spec+tests in one commit, human-approved separate commit for deletions), and the audit section gives remediation branches for both failure modes plus when-to-run triggers. Not a 5 because there is no explicit re-run-the-audit loop after remediation, and the validation script itself is unshipped. | 4 / 5 |
Progressive Disclosure | A ~65-line body organized into five clear sections with no nested references, appropriate for a single-file skill. Not a 5: the body exceeds the under-50-lines simple-skill threshold and its one external reference (`scripts/trace-audit.bb`) points to a file absent from the bundle. | 4 / 5 |
Total | 16 / 20 Passed |