213 lines
4.5 KiB
Markdown
213 lines
4.5 KiB
Markdown
---
|
|
description: Resolve [NEEDS CLARIFICATION] markers interactively
|
|
---
|
|
|
|
# Spec Kit: Clarify Specifications
|
|
|
|
Find and resolve all `[NEEDS CLARIFICATION]` markers in specifications.
|
|
|
|
## Process
|
|
|
|
### Step 1: Find All Clarifications
|
|
|
|
Scan `specs/` for `[NEEDS CLARIFICATION]` markers:
|
|
|
|
```bash
|
|
grep -r "\[NEEDS CLARIFICATION\]" specs/
|
|
```
|
|
|
|
Create a list:
|
|
```markdown
|
|
## Clarifications Needed
|
|
|
|
### High Priority (P0)
|
|
1. **user-authentication.md:**
|
|
- [NEEDS CLARIFICATION] Password reset: email link or SMS code?
|
|
|
|
2. **photo-upload.md:**
|
|
- [NEEDS CLARIFICATION] Max file size: 5MB or 10MB?
|
|
- [NEEDS CLARIFICATION] Supported formats: just images or also videos?
|
|
|
|
### Medium Priority (P1)
|
|
3. **analytics-dashboard.md:**
|
|
- [NEEDS CLARIFICATION] Chart types: line, bar, pie, or all three?
|
|
- [NEEDS CLARIFICATION] Real-time updates or daily aggregates?
|
|
|
|
[... list all ...]
|
|
```
|
|
|
|
### Step 2: Ask Questions by Priority
|
|
|
|
**For each clarification (P0 first):**
|
|
|
|
```
|
|
**Feature:** user-authentication
|
|
**Question:** For password reset, should we use email link or SMS code?
|
|
|
|
**Context:**
|
|
- Email link: More secure, standard approach
|
|
- SMS code: Faster, but requires phone number
|
|
|
|
**Recommendation:** Email link (industry standard)
|
|
|
|
What would you prefer?
|
|
```
|
|
|
|
### Step 3: Record Answers
|
|
|
|
For each answer received:
|
|
|
|
```markdown
|
|
## Answer: Password Reset Method
|
|
|
|
**Question:** Email link or SMS code?
|
|
**Answer:** Email link with 1-hour expiration
|
|
**Additional Details:**
|
|
- Link format: /reset-password?token={jwt}
|
|
- Token expires: 1 hour
|
|
- Email template: Branded with reset button
|
|
```
|
|
|
|
### Step 4: Update Specifications
|
|
|
|
For each answer, update the corresponding specification:
|
|
|
|
**Before:**
|
|
```markdown
|
|
## Password Reset
|
|
|
|
[NEEDS CLARIFICATION] Should we use email link or SMS code?
|
|
```
|
|
|
|
**After:**
|
|
```markdown
|
|
## Password Reset
|
|
|
|
Users can reset their password via email link.
|
|
|
|
**Implementation:**
|
|
- User requests reset via /api/auth/reset-password
|
|
- System sends email with unique token (JWT, 1-hour expiry)
|
|
- Email contains link: /reset-password?token={jwt}
|
|
- User clicks link, enters new password
|
|
- Token validated, password updated
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] User can request password reset
|
|
- [ ] Email sent within 30 seconds
|
|
- [ ] Link expires after 1 hour
|
|
- [ ] Token is single-use
|
|
- [ ] Password successfully updated after reset
|
|
```
|
|
|
|
### Step 5: Cross-Reference Updates
|
|
|
|
If clarification affects multiple specs, update all:
|
|
|
|
Example: Max file size affects both photo-upload and document-upload specs
|
|
|
|
### Step 6: Validate Completeness
|
|
|
|
After all clarifications:
|
|
|
|
```bash
|
|
# Check no markers remain
|
|
grep -r "\[NEEDS CLARIFICATION\]" specs/
|
|
|
|
# Should return: No matches (or only in comments/examples)
|
|
```
|
|
|
|
---
|
|
|
|
## Output Format
|
|
|
|
```markdown
|
|
# Clarification Session Complete
|
|
|
|
**Date:** {{DATE}}
|
|
**Clarifications resolved:** X
|
|
|
|
## Summary
|
|
|
|
### Photo Upload Feature
|
|
✅ Max file size: 10MB
|
|
✅ Supported formats: JPEG, PNG, WebP
|
|
✅ Upload method: Drag-drop and click-browse (both)
|
|
✅ Max photos per item: 10
|
|
|
|
### Analytics Dashboard
|
|
✅ Chart types: Line, bar, pie (all three)
|
|
✅ Data refresh: Real-time for alerts, daily aggregates for charts
|
|
✅ Date ranges: 7d, 30d, 90d, all time
|
|
|
|
### User Authentication
|
|
✅ Password reset: Email link (1-hour expiry)
|
|
✅ Session duration: 24 hours (configurable)
|
|
✅ Rate limiting: 10 attempts per hour
|
|
|
|
[... all clarifications ...]
|
|
|
|
## Specifications Updated
|
|
|
|
Updated X specifications:
|
|
1. user-authentication.md
|
|
2. photo-upload.md
|
|
3. analytics-dashboard.md
|
|
[...]
|
|
|
|
## Validation
|
|
|
|
✅ No [NEEDS CLARIFICATION] markers remaining
|
|
✅ All acceptance criteria complete
|
|
✅ Specifications ready for implementation
|
|
|
|
## Next Steps
|
|
|
|
Ready for Gear 6: Implementation
|
|
|
|
Use `/speckit.tasks` and `/speckit.implement` for each feature.
|
|
```
|
|
|
|
---
|
|
|
|
## Defer Mode
|
|
|
|
If clarifications_strategy = "defer":
|
|
|
|
Instead of asking questions, just document them:
|
|
|
|
```markdown
|
|
# Deferred Clarifications
|
|
|
|
**File:** .specify/memory/deferred-clarifications.md
|
|
|
|
## Items to Clarify Later
|
|
|
|
1. **photo-upload.md:**
|
|
- Max file size?
|
|
- Supported formats?
|
|
|
|
2. **analytics-dashboard.md:**
|
|
- Chart types?
|
|
- Real-time or aggregated?
|
|
|
|
[... list all ...]
|
|
|
|
## How to Resolve
|
|
|
|
When ready, run `/speckit.clarify` to answer these questions.
|
|
```
|
|
|
|
Then continue with implementation of fully-specified features.
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- Ask questions in priority order (P0 first)
|
|
- Provide context and recommendations
|
|
- Allow "defer to later" for non-critical clarifications
|
|
- Update all related specs when answering
|
|
- Validate no markers remain at the end
|
|
- If user is unsure, mark as P2/P3 (lower priority)
|