Content
63%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 genuinely executable workflow: exact commands, file paths, gate checks, and a completion checklist give Claude unambiguous instructions for the happy path. Its main weaknesses are structural — the hook protocol is duplicated verbatim across pre- and post-execution sections, inflating token cost, and the artifact-generation phases lean on an external template whose content is never surfaced.
Suggestions
Extract the hook rules (YAML error handling, enabled/condition filtering, dot-to-hyphen mapping, emission blocks) into a single shared section or reference file and have both Pre-Execution and Post-Execution sections point to it, removing ~30 duplicated lines.
Define what happens after an ERROR state (e.g. 'on gate failure, report the violation and stop; do not generate Phase 1 artifacts') so the validation checkpoints have recovery paths, not just failure signals.
Show a brief outline of the IMPL_PLAN template's structure (section names for Technical Context, Constitution Check, phases) so the 'Execute plan workflow' step does not depend entirely on an unseen file.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is terse and imperative with no explanation of concepts Claude already knows, but the entire hook protocol (YAML parse-error handling, 'Filter out hooks where `enabled` is explicitly `false`', condition handling, the dot-to-hyphen replacement rule, and the emission blocks) is repeated nearly verbatim in both 'Pre-Execution Checks' and 'Mandatory Post-Execution Hooks' — roughly 30 duplicated lines that a shared rules section would eliminate. This is more than the 'minor instances' of anchor 4, fitting anchor 3's 'mostly efficient but could be tightened', though not anchor 2 since there is no conceptual padding. | 3 / 5 |
Actionability | Concrete, executable guidance dominates: the exact command '.specify/scripts/bash/setup-plan.sh --json', specific paths ('.specify/extensions.yml', '.specify/memory/constitution.md'), named artifacts, a shell-quoting escape example, and precise skip/emit rules. Minor gaps keep it below anchor 5: the research dispatch block is placeholder text ('Task: "Research {unknown} for {feature context}"') and the core execution depends on an IMPL_PLAN template whose structure is never shown. | 4 / 5 |
Workflow Clarity | The sequence is clearly ordered (Pre-Execution Checks → Outline → Phase 0 → Phase 1 → Post-Execution Hooks → Completion Report) with explicit checkpoints: Constitution Check with re-evaluation post-design, 'ERROR if violations unjustified', 'ERROR on gate failures or unresolved clarifications', a 'Prerequisites: research.md complete' gate, and a 'Done When' checklist. It falls short of anchor 5 because ERROR states define failure conditions but no recovery/feedback path for what to do after an ERROR. | 4 / 5 |
Progressive Disclosure | Sections are well-organized with clear headers, but roughly 60 of the ~160 lines are hook mechanics that (being shared across speckit commands and duplicated twice) clearly belong in a separate reference file, and no bundle references exist at all. This matches anchor 3 ('content that should be separate is inline'); it is not 2 because the inlined content is still navigable under clear headings, and not 4 because the misplaced bulk exceeds 'minor organization gaps'. | 3 / 5 |
Total | 14 / 20 Passed |