Spec-Clarify
Reduce ambiguity in specifications through targeted questioning.
Prerequisites: Feature spec must exist (run /spec-specify first).
Workflow
- Initialize - Run
.specify/scripts/bash/check-prerequisites.sh --json --paths-only
- Load spec - Read spec.md
- Scan ambiguity - Analyze coverage taxonomy
- Generate questions - Max 5, prioritized by impact
- Question loop - Present ONE at a time with recommendation
- Integrate answers - Update spec after each answer
- Report - Output summary and next steps
Ambiguity Taxonomy
Categories to scan (mark Clear/Partial/Missing):
| Category |
Check For |
| Functional Scope |
User goals, out-of-scope, personas |
| Data Model |
Entities, relationships, constraints |
| UX Flow |
Journeys, error states, accessibility |
| Non-Functional |
Performance, security, observability |
| Integration |
External APIs, formats, versioning |
| Edge Cases |
Negative scenarios, rate limits |
Question Format
Multiple Choice:
**Recommended:** Option A - <reasoning>
| Option | Description |
|--------|-------------|
| A | Option A |
| B | Option B |
| Short | Custom answer (<=5 words) |
Short Answer:
**Suggested:** <answer> - <reasoning>
Format: <=5 words. Say "yes" or provide your own.
Integration Rules
After each answer:
- Add
## Clarifications section if missing
- Add
### Session YYYY-MM-DD subheading
- Append:
- Q: <question> → A: <answer>
- Update relevant spec section
- Save immediately
Constraints
- Max 5 questions asked
- Max 10 questions total across session
- Respect "done", "stop", "proceed" signals
Next Steps
After /spec-clarify:
/spec-plan - Create technical plan
