| name | sdd-clarify |
| description | Spec-Driven Development: Ambiguity detection taxonomy, prioritization heuristic, and sequential questioning protocol |
Ambiguity Detection and Clarification
The clarify step resolves ambiguities in a feature spec through structured questioning. The goal is to fill critical gaps before planning begins — not to achieve perfection.
Ambiguity Taxonomy (11 Categories)
Scan the spec for ambiguities across these categories:
- Functional Scope — Unclear boundaries: what's in vs. out of this feature? What adjacent behaviors are excluded?
- Domain/Data — Undefined entities, unclear relationships, missing data shapes or validation rules
- UX Flow — Unclear user journeys, missing steps between screens/states, ambiguous interaction sequences
- Non-Functional — Missing performance targets, scale assumptions, reliability requirements, or SLA expectations
- Integration — Unspecified interactions with external systems, APIs, or third-party services
- Edge Cases — Unhandled boundary conditions, concurrent access scenarios, failure modes
- Constraints — Unclear business rules, regulatory/compliance requirements, or technical limitations
- Terminology — Ambiguous domain terms that could be interpreted differently by different stakeholders
- Completion Signals — Unclear definition of "done" — how will success be measured in production?
- Placeholders — Explicit
[NEEDS CLARIFICATION] markers left in the spec
- Unresolved — Conflicting requirements or contradictory assumptions within the spec
Prioritization Heuristic
For each ambiguity found, score it: Priority = Impact × Uncertainty
- Impact (1–3): How much does this ambiguity affect architecture, data model, API contracts, test strategy, UX, or compliance?
- 1 = cosmetic/wording only
- 2 = affects task breakdown or test coverage
- 3 = affects architecture, data model, or compliance
- Uncertainty (1–3): How unclear is this?
- 1 = reasonable default is obvious
- 2 = multiple valid interpretations, no clear winner
- 3 = fundamentally unknown, must ask
Only ask about ambiguities with score ≥ 4. Lower-score ambiguities should be resolved using reasonable defaults.
Questioning Protocol
Rules:
- Maximum 5 questions — prioritize the highest-scoring ambiguities
- One question at a time — wait for the answer before asking the next
- Multiple-choice format — always provide options with a recommended choice
- One clear recommendation — mark the best option as
(recommended) based on common practice
Question format:
**Question [N]/[max]: [Category]**
[Clear, specific question — what exactly needs to be decided?]
Options:
A. [Option A description] (recommended)
B. [Option B description]
C. [Option C description]
D. Other — please describe
Why multiple-choice? It anchors the conversation, reduces back-and-forth, and forces the agent to have thought through the options. It also makes it easy for the user to accept a default.
Spec Update Protocol
After each answer:
- Update the spec inline — find the most relevant section (FR, SC, Edge Cases, Assumptions) and update it to reflect the decision
- Record the Q&A — append to the
## Clarifications section:
## Clarifications
### Session YYYY-MM-DD
**Q1 [Functional Scope]**: [Question text]
**A**: [Answer received]
**Impact**: Updated FR-003 to clarify that [decision]. Added edge case for [scenario].
**Q2 [Domain/Data]**: [Question text]
**A**: [Answer received]
**Impact**: Updated Key Entities — User entity now includes [attribute].
Coverage Summary
After all questions are answered (or the 5-question limit is reached), provide a coverage summary table:
## Clarification Coverage Summary
| Category | Status |
|----------|--------|
| Functional Scope | ✅ Resolved |
| Domain/Data | ✅ Resolved |
| UX Flow | ⏭ Deferred (reasonable default applied) |
| Non-Functional | ✅ Resolved |
| Integration | ➖ Not applicable |
| Edge Cases | ✅ Resolved |
| Constraints | ⏭ Deferred |
| Terminology | ✅ Resolved |
| Completion Signals | ✅ Resolved |
| Placeholders | ✅ All [NEEDS CLARIFICATION] markers resolved |
| Unresolved | ✅ No conflicts found |
Status values:
- ✅ Resolved — question asked and answered, spec updated
- ⏭ Deferred — reasonable default applied, documented in Assumptions
- ➖ Not applicable — category has no ambiguities in this spec
- ⚠ Outstanding — ambiguity exists but question limit reached (document as risk)
When to Stop Without Asking
Do NOT ask about ambiguities that:
- Have an obvious industry-standard default (e.g., "should passwords be hashed?" — yes, always)
- Are purely cosmetic (e.g., exact button label text)
- Would only affect P3 (nice-to-have) requirements
- Can be trivially reversed without architectural impact
Document these as Assumptions instead.
