Content
82%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: concrete gh commands with verification steps and explicit approval gates for every mutation, and clean sectioning. The main costs are repetition of the 'no implementation details' rule across four places, a slightly redundant Quick Reference table, and a ~250-line monolith whose PR-finalization and refining sections could live in reference files.
Suggestions
State the 'no implementation details in the body' rule once (the blockquote is the strongest placement) and let the 'Don't' list carry a single reminder line instead of restating it in 'Before Creating' and 'Refining an Existing Issue'.
Add one line to the Flow covering what to do when post-create verification shows the wrong title, type, or state (e.g. fix with `gh issue edit` and re-verify), closing the error-recovery loop.
Drop the 'Quick Reference' table (it duplicates commands already shown verbatim) and consider moving 'Finalization' / PR creation into a separate reference file to shrink the always-loaded body.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is largely lean and imperative with zero time spent explaining concepts Claude already knows, but the no-implementation-details rule is stated four times (the blockquote, 'Before Creating', 'Refining an Existing Issue', and the 'Don't' list), and the opening bold paragraphs plus the 'Quick Reference' table restate content already given. Not 3: the rest of the file is tight, so the padding is a minor trim rather than a pervasive problem; not 5: the repeated rule and duplicate table are over-explanation that could be cut. | 4 / 5 |
Actionability | Every operation has a copy-paste-ready command: full `gh issue create` invocations with example bodies for both leaf and tracker shapes, `gh issue view --json ...` verification, `gh issue edit --body-file`, and a complete `gh pr create --draft` example ending in `Closes #<issue-number>`. The common cases (create, verify, edit, PR) are all covered with concrete approval-gate instructions between them. | 5 / 5 |
Workflow Clarity | The 'Flow' section gives a clear 6-step sequence with explicit checkpoints — 'wait for Josh's approval of that exact text', 'verify what landed' via `gh issue view --json`, and the edit path is view → apply → verify. Not 5: there is no error-recovery loop telling Claude what to do when the post-create/post-edit verification shows the issue landed wrong, which is the missing feedback loop the top anchor asks for; not 3: verification checkpoints are explicit and present everywhere, not merely implicit. | 4 / 5 |
Progressive Disclosure | The single file is well-sectioned with clear headings and no nested references — every cross-reference (CLAUDE.md rules, the `github` skill) is one level deep and clearly signaled. Not 5: at ~250 lines everything is inline; the Quick Reference table, the PR-finalization section, and the refining guidance are candidates for split-out reference files, which keeps it short of the 'content appropriately split' top anchor; not 3: structure and navigation are good, with no buried references. | 4 / 5 |
Total | 17 / 20 Passed |