Content
88%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 an operationally dense, executable procedure: copy-paste-ready commands, explicit validation and error-recovery loops, and rationales that document genuinely non-obvious project constraints rather than things Claude already knows. Its only weaknesses are slight narrative padding and a single long inline block of flag documentation that could be split out.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Nearly every passage carries non-obvious project knowledge (why `.closingIssuesReferences[0].number` mis-resolves, why the whole `.claude/metrics/` directory must not be staged). Only minor narrative could be trimmed ('Where this sits', some framing in 'When to run this instead of `retro`'), fitting the efficient-with-minor-trimmings anchor. | 4 / 5 |
Actionability | Fully executable throughout: environment probes, both `bun run --cwd tools/pr-metrics card` invocations with flag semantics, the slug/commit/push script, the append-only PR-body edit, and the duplicate-check grep. Fallbacks for no-`gh`, no-network, and exit-1 cases are enumerated. | 5 / 5 |
Workflow Clarity | Clear sequence (probe environment → write and commit the card → render onto the PR → report) with explicit validation checkpoints: check the card is not already on the body, verify the issue the card names and rerun with `--issue <n>`, append rather than rebuild the PR body, and recovery paths for each failure mode. | 5 / 5 |
Progressive Disclosure | Well-organized single file with clear section headers and no nested references. The ~45 lines of flag-lookup rules in Step 1 are the one block of detail that could live in a separate reference file, leaving minor organization gaps rather than the clean split of the top anchor. | 4 / 5 |
Total | 18 / 20 Passed |