Content
78%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 strong, highly actionable body with concrete decision rules, copy-paste examples, and an explicit pre-commit validation step, supported by a clean two-file reference structure that follows progressive disclosure well. The main weakness is token efficiency: it re-explains spec knowledge Claude already has (type table, SemVer mapping in Mindset) and duplicates rules and an example across sections.
Suggestions
Trim the Mindset section and Type Reference table — Claude already knows the standard Conventional Commits types and their SemVer mapping; keep only the decision rules for ambiguous cases (refactor vs feat, chore as last resort) which are the genuinely non-obvious guidance.
Remove the duplication: the `feat(auth): add OAuth2 login support` example appears both in the agent output format and in Examples, and the header rules (imperative, lowercase, ≤72 chars) are stated in Procedure steps 4–6 and repeated under 'Rules' — state each once.
Add a short feedback loop to Procedure step 7 (e.g., 'if commitlint reports a violation, fix the header/body and re-run before committing') to upgrade the validation checkpoint into a recovery path.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient but includes unnecessary explanation and duplication: the Mindset section restates the Conventional Commits/SemVer contract ("`feat` triggers a MINOR version bump, `fix` triggers PATCH") and the Type Reference table re-lists standard spec types Claude already knows; the `feat(auth): add OAuth2 login support` example appears twice (Procedure output format and Examples), and the 72-char/imperative rules are stated in Procedure steps 4–6 and again under Rules. Not level 4: the redundancy (duplicated example, repeated rules, known-spec table) is more than minor trimming; not level 2: the bulk is genuinely useful judgment content with no padding prose. | 3 / 5 |
Actionability | Fully executable guidance: a format template, copy-paste-ready example messages covering feature/fix/breaking/perf cases, concrete decision rules for ambiguities ("does the user gain new capability? If yes → `feat`"), and runnable commands (`echo "feat(auth): add OAuth2 login support" | npx commitlint`, `git log --format="%s" HEAD~5..`). Not level 4: common cases are covered with copy-paste-ready output plus a ready-to-paste agent output format. | 5 / 5 |
Workflow Clarity | The Procedure is a clearly sequenced 7 steps with an explicit verification checkpoint ("run `git commit --dry-run` or your local commitlint hook"), and the 'If applied, this commit will' check is a concrete validation heuristic. Not level 5: there is no feedback loop for error recovery (what to do when validation fails) and no checklist; the validation step exists but recovery handling is implicit. Not level 3: validation is explicitly present as a numbered step, not missing. | 4 / 5 |
Progressive Disclosure | Clear overview with well-signaled, one-level-deep references that exist in the bundle (references/scope-and-strategy.md, references/tooling.md); deeper material (scope vocabulary, commitlint/semantic-release setup) is appropriately split out, inline links are descriptive, and the References section annotates each file plus external spec links. Not level 4: navigation is clean, both referenced paths resolve to real files, and nothing that belongs in a reference is inlined. | 5 / 5 |
Total | 17 / 20 Passed |