Content
85%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 a tight, well-structured decision tree: a clear four-phase workflow with explicit branch conditions, validation checkpoints, and error-recovery fallbacks at every fragile point, plus one purposeful one-level-deep reference. Its only real weaknesses are minor: a few rationale-heavy sentences that could be trimmed and slightly incomplete inline command detail for the Spiral path.
Suggestions
Trim the explanatory asides that restate the reference's content inline (the "naive config scan misreads ce-setup's commented template" sentence and the duplicated Spiral-optionality framing) to save tokens.
Inline the single `spiral write` invocation skeleton (flags only, e.g. `--instant --json`) in Path A so the happy path is executable without opening the reference.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with instructions and assumes Claude's competence (no explanation of what git or a changelog is), but a few rationale-heavy passages could be trimmed — e.g. the "a naive config scan misreads ce-setup's commented template example" aside and the double explanation of Spiral optionality in the intro and Path B. Anchor 4 (efficient, minor over-explanation) rather than anchor 5's every-token-earns-its-place. | 4 / 5 |
Actionability | Guidance is mostly executable: copy-paste commands (`gh pr view --json title,body,url`, `git diff main...HEAD --stat`, `which spiral`, `spiral auth status --json 2>/dev/null`), a concrete output template, and per-channel shape specs. Minor gaps remain — the actual `spiral write` invocation and its flag semantics are delegated to the reference, and the Phase 1 fallback ordering of sources is left to judgment. Anchor 4 rather than anchor 5's fully copy-paste-ready common cases. | 4 / 5 |
Workflow Clarity | The four phases are explicitly sequenced with a validation checkpoint at the fragile point: the Spiral state detection (Ready/Absent/Unauthed) gates which path runs, Phase 1 has an ask-don't-guess checkpoint ("ask one short question rather than guessing"), and every failure mode has an explicit recovery fallback ("fall back silently to Path B", "never let a Spiral failure... block the skill", Path 0 decline always proceeds). This matches anchor 5's explicit validation steps with error-recovery feedback loops. | 5 / 5 |
Progressive Disclosure | The body is a well-organized decision tree (~80 lines) that keeps the detailed CLI mechanics in one clearly-signaled, one-level-deep reference: `references/spiral-cli.md` is cited twice with explicit purpose ("Read ... before composing the prompt"; "read ... and follow its Path 0 section"), and that file exists with the cited Path 0 section and the cue-word/`--num-drafts` gotcha the body defers to. Anchor 5: clear overview, well-signaled references, easy navigation. | 5 / 5 |
Total | 18 / 20 Passed |