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.
The body is highly actionable with concrete commands, exact classification rules, complete templates, and unusually strong validation checkpoints (the provenance check with hard stops is a genuine strength). The main weaknesses are runtime-irrelevant commentary padding the provenance section and a duplicate "Phase 7" heading that breaks the phase numbering.
Suggestions
Move or delete the maintainer-facing commentary ("This rule is kept identical to /patch-notes' on purpose... Change both together" and the extended "Why this is a hard stop" narrative), keeping only the operative rule and one line of rationale — this trims the provenance section substantially without losing the check itself.
Fix the duplicate phase numbering: rename the second "Phase 7: Next Steps" to "Phase 8" (or merge it into Phase 6 output guidance) so the sequence is unambiguous.
Condense the inline justifications (e.g., the thousands-of-lines rationale in Phase 2) to their operative instruction — "bound the range to 100 commits; if insufficient, ask for a start ref" — to reduce token load.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly efficient — exact git commands, terse category definitions, ready-to-fill templates — but the provenance section carries runtime-irrelevant material: the maintainer commentary "This rule is kept identical to /patch-notes' on purpose... Change both together", the extended "Why this is a hard stop" failure narrative, and justifications like "on an established repo that is thousands of lines...". This fits anchor 3 (mostly efficient but includes some unnecessary explanation or could be tightened) better than anchor 4. | 3 / 5 |
Actionability | Fully executable throughout: `git log --oneline [last-tag]..HEAD`, `git rev-parse --is-inside-work-tree`, explicit commit-classification rules with concrete task-ID patterns ([STORY-123], TR-, #NNN), two complete output templates, and an exact scripted user prompt for the file-write offer. Commands are copy-paste ready and the templates cover the common cases. | 5 / 5 |
Workflow Clarity | The phase sequence is clear with strong validation checkpoints (provenance classification with hard BLOCKED stops and exact stop messages, repo verification, no-history branch, checking docs/CHANGELOG.md existence before asking, and append/overwrite/decline branches). It falls short of anchor 5 because the document contains two sections both numbered "Phase 7" ("Offer File Write" and "Next Steps"), a numbering defect that muddies step identification. | 4 / 5 |
Progressive Disclosure | No bundle files exist and all content is needed on every invocation, so inline placement is largely appropriate with clear section headers. However, at ~250 lines the body carries rationale blocks and maintainer commentary that could live in a reference file or be cut, and the numbered-phase organization is undercut by the duplicated Phase 7 heading — good structure with minor organization gaps fits anchor 4. | 4 / 5 |
Total | 16 / 20 Passed |