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 highly actionable body with copy-paste commands, an exact entry format, a clearly sequenced workflow with a validation step, and a well-organized reference bundle. The main weakness is repetition: the same directives (read-before-append, prefer generate over hand-typing) are stated multiple times across sections, and a couple of sections (Where Rules Live, the When to Use trigger list) restate information already conveyed elsewhere.
Suggestions
Cut the one-sentence 'Where Rules Live' section and state the path (.claude/RULES.md) directly in Prerequisites; the current 'path shown in Quick Start above' indirection costs a section to convey one fact.
State the read-before-append and prefer-generate-over-hand-typing directives once each (in the numbered workflow) instead of repeating them in Prerequisites, Anti-Patterns, and Mindset.
Add an error-recovery step to the workflow: 'If validate-rules.sh validate fails, fix the entry and re-run before treating the change as done' -- this closes the feedback-loop gap and would raise workflow clarity to anchor 5.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly efficient but repeats itself noticeably: the read-before-append directive appears in Prerequisites, step 1 of When to Use, the first Anti-Pattern, and Mindset; 'When to Use' restates the description's full trigger list; the one-sentence 'Where Rules Live' section adds nothing beyond Quick Start; and 'TYPICALLY this is the same command as the Quick Start validation step' is meta-commentary. This matches anchor 3 ('mostly efficient but includes some unnecessary explanation or could be tightened') better than anchor 4, where over-explanation would be only minor. | 3 / 5 |
Actionability | Fully executable, copy-paste-ready commands cover the common case: 'cat .claude/RULES.md', './scripts/validate-rules.sh validate .claude/RULES.md', and './scripts/validate-rules.sh generate "<title>" "<directive>" "<rationale>"', backed by a concrete entry template and real schema/template bundle files. This matches anchor 5. | 5 / 5 |
Workflow Clarity | A clear numbered 1-5 sequence (read, dedupe-check, append via generate, inform user, validate before done) with an explicit validation checkpoint before treating the change as complete. It falls short of anchor 5 because there is no error-recovery feedback loop saying what to do when 'validate-rules.sh validate' fails (fix and re-validate), which the anchor-5 example includes. | 4 / 5 |
Progressive Disclosure | The References section clearly signals existing one-level-deep files (references/rule-format.md, assets/schemas/rule-entry.schema.json, assets/templates/rule-entry.yaml) and the Quick Start orients the reader immediately. However, the body's 'Rule Format' section duplicates the core of references/rule-format.md inline rather than fully splitting it out, a minor organization gap that fits anchor 4 rather than anchor 5. | 4 / 5 |
Total | 16 / 20 Passed |