Purpose: Catch spec gaps BEFORE they survive into exploration, design, and implementation.
When to Dispatch
After Phase 1 (brainstorm) writes .planning/SPEC.md and before Phase 2 (explore) begins.
Phase 1: Brainstorm → SPEC.md written
→ [THIS SKILL] Dispatch spec reviewer subagent
→ Issues found? Fix SPEC.md → re-dispatch reviewer
→ Approved? → Phase 2: Explore
NO EXPLORATION WITHOUT REVIEWED SPEC. This is not negotiable.
A bad spec that survives into exploration means:
- Exploring the wrong areas of the codebase
- Clarifying the wrong ambiguities
- Designing against incomplete requirements
- Implementing the wrong thing
Catching a spec gap NOW costs 1 minute. Catching it during implementation costs hours.
Spec Review Facts
- User confirmation verifies intent, not completeness — the user approves what they asked for, not what implementation needs (error handling, testing strategy, measurable success criteria). Treating user sign-off as a substitute for the reviewer is an unverified completeness claim presented as fact.
- Self-review of a spec you just wrote rubber-stamps your own assumptions; the gate exists because only an independent reviewer subagent catches them. Skipping the 30-second dispatch trades it against hours of rework — counterproductive on its own terms.
Dispatch Template
Use this Task invocation to dispatch the spec reviewer:
Agent(
subagent_type="general-purpose",
allowed_tools=["Read", "Glob", "Grep", "Bash(read-only)"],
description="Review spec document",
prompt="""
You are a spec document reviewer. Verify this spec is complete and ready for codebase exploration and implementation planning.
**Tool Restrictions:** You are READ-ONLY. You MUST NOT use Write or Edit tools. You read `.planning/SPEC.md`, evaluate it against the checklist, and return a verdict. If you find issues, you report them — the main chat fixes them.
**Spec to review:** .planning/SPEC.md
Read the spec file, then evaluate against ALL categories below.
## What to Check
| Category | What to Look For |
|----------|------------------|
| Completeness | TODOs, placeholders, "TBD", incomplete sections, empty fields |
| Coverage | Missing error handling, edge cases, integration points |
| Consistency | Internal contradictions, conflicting requirements |
| Clarity | Ambiguous requirements that could be interpreted multiple ways |
| YAGNI | Unrequested features, over-engineering, gold-plating |
| Scope | Focused enough for a single implementation — not covering multiple independent features |
| Testing | Testing strategy section filled (not empty or "manual only") |
| Success Criteria | Measurable, specific, with clear pass/fail (not vague) |
## CRITICAL — Look Especially Hard For:
- Any TODO markers or placeholder text
- Sections saying "to be defined later" or "will spec when X is done"
- Sections noticeably less detailed than others
- Testing strategy that says "manual" (this is a BLOCKER in workflows:dev)
- Success criteria that are vague ("works well", "is fast", "handles errors")
- Requirements that contradict each other
- Missing constraints section
## Output Format
## Spec Review
**Status:** APPROVED | ISSUES_FOUND
**Issues (if any):**
- [Section]: [specific issue] - [why it matters for implementation]
**Recommendations (advisory — don't block approval):**
- [suggestions for improvement that aren't blocking]
""")
Handling Reviewer Output
If APPROVED
Proceed immediately to Phase 2 (explore):
Read ${CLAUDE_SKILL_DIR}/../../skills/dev-explore/SKILL.md and follow its instructions.
If ISSUES_FOUND
- Fix the specific issues in
.planning/SPEC.md - Re-dispatch the reviewer (same template)
- Repeat until APPROVED or max 5 iterations
If 5 Iterations Without Approval
Escalate to user:
"Spec reviewer has flagged issues 5 times. Remaining issues:
[list issues]
Should I: (A) Fix these, (B) Proceed with known gaps, (C) Rethink the spec?"
Gate Function
1. IDENTIFY: `.planning/SPEC.md` exists
2. DISPATCH: Send to reviewer subagent
3. READ: Reviewer returns APPROVED or ISSUES_FOUND
4. VERIFY: If ISSUES_FOUND, fix and re-dispatch (max 5)
5. CLAIM: Only proceed to explore when APPROVED