Content
86%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 well-organized, token-efficient workflow document that splits detail appropriately into one referenced file and gates its only destructive operation (label changes) behind user confirmation. The main weakness is vague GitHub-API invocation guidance and the absence of an explicit error-recovery loop in the analysis step.
Suggestions
Replace 'Use the GitHub API to get the full list of PRs merged within the specified range' with a concrete command or endpoint example (e.g. a `gh pr list --state merged --search ...` invocation) so the retrieval step is fully executable.
Add a brief validation/retry checkpoint in Step 1 or 2 (e.g. re-confirm a borderline classification against references/classification.md before presenting it) to introduce an explicit error-recovery feedback loop into the analysis pass.
In Step 3, note what to do if the user is unsure or declines to confirm a label change, so the reconciliation flow has a defined terminal state rather than an implicit abort.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and assumes Claude's competence — it never explains what a PR or breaking change is conceptually, and every section (Input, Process steps, Output) earns its place with no padding, matching the 'every token earns its place' anchor. | 5 / 5 |
Actionability | Concrete commit-range formats with examples, explicit classification categories, impact dimensions, and a spelled-out reconciliation flow give mostly actionable guidance; the gap is that GitHub API access is stated only as 'Use the GitHub API' with no specific endpoint or gh command, leaving a minor execution detail to Claude. | 4 / 5 |
Workflow Clarity | Four clearly sequenced steps with an interactive user-confirmation checkpoint governing the destructive label add/remove operations and an input-validation prompt when no range is given; falls short of a 5 because there is no explicit error-recovery or re-validation loop for the analysis pass itself. | 4 / 5 |
Progressive Disclosure | The body is a clear overview that defers the detailed classification guide to a single one-level-deep, well-signaled reference (references/classification.md, verified to exist) with an inline link and a description of what it contains, matching the clear-overview anchor. | 5 / 5 |
Total | 18 / 20 Passed |