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.
This is a highly actionable, well-sequenced process skill: every step carries exact commands, tool invocations, or templates, with user-review checkpoints and useful operational gotchas. Weaknesses are minor — some redundancy in the diagram mandate, a mechanism-heavy step-8 paragraph that belongs in the referenced handoff skill, and no explicit validation of the produced spec/diagrams before handoff.
Suggestions
Add an explicit validation checkpoint before retain/handoff, e.g. re-read docs/specs/<feature-name>.md to confirm all sections are filled and both diagram files exist on disk.
Trim the step-8 spawn_task/worktree mechanism detail to a short note and let the referenced devflow:phase-handoff skill own that behavior description.
State the diagram requirement once (either in the complexity callout or in step 4) to remove the duplicated mandate.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is imperative and directive with no explanations of concepts Claude already knows, but has minor trim candidates: the step-8 mechanism narrative ("visible in the sidebar", "durable across worktree removal") and the diagram mandate stated twice ("REQUIRED for any non-trivial feature — this is the devflow default" then "Every non-trivial spec ships a rendered technical diagram AND an ELI5 diagram by default"). | 4 / 5 |
Actionability | Fully executable instruction-only guidance: exact bash snippet for the window title, an exact mark_chapter call with arguments, a ticket-ID regex, a complete copy-paste spec template at docs/specs/<feature-name>.md, an exact handoff invocation (devflow:phase-handoff --phase spec --next-phase plan), and specific operational gotchas like "one image per turn — batching an image Read with any other tool call suppresses the inline preview". | 5 / 5 |
Workflow Clarity | Eight clearly numbered, dependency-ordered steps with explicit user checkpoints ("If arguments are vague, ask clarifying questions", "list them and ask the user to pick", step 6's present-for-review questions), but with minor validation gaps — no explicit verification that the diagrams rendered successfully or that the spec document is complete before retain/handoff. | 4 / 5 |
Progressive Disclosure | No bundle files exist (references/, scripts/, assets/ are absent), so scoring is against structure and placement: sections are well-organized (Preamble / Steps / Important) and the template and one-liner commands belong inline; the only gap is the dense step-8 paragraph detailing spawn_task/worktree mechanics that would fit better in the referenced handoff skill than inlined here. | 4 / 5 |
Total | 17 / 20 Passed |