Clarification Phase: Standard Operating Procedure

Training Guide: Step-by-step procedures for executing the /clarify command to resolve ambiguities efficiently.

Supporting references:

• reference.md - Question generation strategies, prioritization matrix, integration patterns
• examples.md - Good questions (specific, scope-defining) vs bad questions (vague, with defaults)
• templates/clarification-template.md - Structured question template

Phase Overview

Purpose: Resolve critical ambiguities in spec.md through structured questions, then integrate answers back into specification.

Inputs:

• specs/NNN-slug/spec.md with [NEEDS CLARIFICATION] markers

Outputs:

• specs/NNN-slug/clarifications.md - Structured questions with user answers
• Updated specs/NNN-slug/spec.md - Resolved requirements, removed markers
• Updated workflow-state.yaml

Expected duration: 5-15 minutes (question generation) + user response time

Prerequisites

Environment checks:

• Spec phase completed (spec.md exists)
• spec.md contains [NEEDS CLARIFICATION] markers (if none, skip /clarify)
• Git working tree clean

Knowledge requirements:

• Question prioritization matrix (Critical > High > Medium > Low)
• Structured question format (Context → Options → Impact)
• Spec integration patterns

Execution Steps

Step 1: Extract Clarification Needs

Actions:

1. Read spec.md to find all [NEEDS CLARIFICATION: ...] markers
2. Extract ambiguity context for each marker
3. Count clarifications found

Example:

# Count clarifications
CLARIFICATION_COUNT=$(grep -c "\[NEEDS CLARIFICATION" specs/NNN-slug/spec.md)
echo "Found $CLARIFICATION_COUNT clarifications"

# List them
grep -n "\[NEEDS CLARIFICATION" specs/NNN-slug/spec.md

Quality check: If count = 0, skip /clarify phase. If count >5, review spec phase (too many clarifications).

Step 2: Prioritize Questions

Actions:

1. Categorize each clarification by priority using matrix (see reference.md):

   • Critical: Scope boundary, security/privacy, breaking changes
   • High: User experience decisions, functionality tradeoffs
   • Medium: Performance SLAs, technical stack choices
   • Low: Error messages, rate limits

2. Keep only Critical + High priority questions

3. Convert Medium/Low to informed guesses (document as assumptions)

Prioritization matrix quick reference:

Target: ≤3 questions total after prioritization.

Quality check: Are all remaining questions scope/security critical?

Step 3: Generate Structured Questions

Actions: For each Critical/High priority clarification, generate structured question using template:

Structured question format:

## Question N: [Short Title]

**Context**: [Explain ambiguity in spec with specific reference]

**Options**:
A. [Option 1 description]
B. [Option 2 description]
C. [Option 3 description]

**Impact**:
- Option A: [Implementation cost + user value + tradeoffs]
- Option B: [Implementation cost + user value + tradeoffs]
- Option C: [Implementation cost + user value + tradeoffs]

**Recommendation**: [Suggested option with rationale]

**References**: [Link to spec.md line with [NEEDS CLARIFICATION] marker]

Example:

## Question 1: Dashboard Metrics Scope

**Context**: spec.md line 45 mentions "student progress tracking" but doesn't specify which metrics to display.

**Options**:
A. Completion rate only (% of lessons finished)
B. Completion + time spent (lessons finished + hours logged)
C. Full analytics (completion + time + quiz scores + engagement metrics)

**Impact**:
- Option A: Fastest (~2 days), basic insights, may require expansion later
- Option B: Moderate (~4 days), actionable insights for identifying struggling students
- Option C: Comprehensive (~7 days), requires analytics infrastructure, future-proof

**Recommendation**: Option B (balances insight with implementation cost)

**References**: specs/042-student-progress-dashboard/spec.md:45

Quality standards for questions:

• Specific: References exact spec location
• Concrete: 2-3 specific options (not open-ended)
• Quantified: Implementation costs in days/hours
• Actionable: User picks A/B/C (not vague descriptions)
• Focused: One question = One decision (no compounds)

Quality check: Does each question follow structured format with clear options?

Step 4: Document Deferred Questions as Assumptions

Actions:

1. For Medium/Low priority questions that were not asked, document as assumptions in clarifications.md
2. Explain why defaults were used instead of asking

Example:

## Deferred Questions (Using Informed Guesses)

### Export Format
**Not asked** (Low priority - standard default exists)
**Assumption**: CSV format (most compatible, industry standard)
**Rationale**: Users can request JSON/Excel in future if needed
**Override**: If requirements differ, specify in spec.md

### Rate Limiting
**Not asked** (Low priority - reasonable default exists)
**Assumption**: 100 requests/minute per user
**Rationale**: Conservative limit prevents abuse, can increase based on usage
**Override**: If higher limits needed, document in spec.md

### Cache Duration
**Not asked** (Medium priority - standard default exists)
**Assumption**: 10-minute cache for dashboard data
**Rationale**: Balances freshness with performance
**Override**: Specify in spec.md if real-time updates required

Quality check: All deferred questions documented with rationale.

Step 5: Create clarifications.md

Actions:

1. Render clarifications.md from template with:

   • Question count and priority breakdown
   • Structured questions (Critical + High only)
   • Deferred questions section (Medium + Low)
   • Instructions for user

2. Add user instructions:

   markdownCopy

   ## Instructions
   
   Please answer the questions below by:
   1. Selecting an option (A/B/C) or providing custom answer
   2. Adding any additional context or constraints
   3. Reviewing deferred assumptions (override if needed)
   
   Once complete, run `/clarify continue` to integrate answers into spec.
   

Quality check: clarifications.md is clear and ready for user review.

Step 6: Wait for User Answers

Actions:

1. Present clarifications.md to user
2. User reviews questions
3. User provides answers (selects options A/B/C or custom)
4. User signals completion

Example user responses:

## Question 1: Dashboard Metrics Scope
**Selected**: Option B (Completion + time spent)
**Additional context**: Also include "last activity date" for staleness detection

## Question 2: User Access Control
**Selected**: Option C (Role-based access)
**Additional context**: Need to add "Parent" role with view-only access to their children's data

## Deferred Assumptions - Overrides
**Rate Limiting**: Use 200 requests/minute instead of 100 (we have power users)

Quality check: User provided clear answers to all questions.

Step 7: Integrate Answers into spec.md

Actions:

1. For each answered question, update spec.md:

   • Locate corresponding [NEEDS CLARIFICATION] marker
   • Replace with concrete requirement based on answer
   • Add details from "additional context"

2. Remove all [NEEDS CLARIFICATION] markers

3. Add "Clarifications (Resolved)" section to spec.md

Example integration:

Before (spec.md):

## Requirements
- Dashboard displays student progress [NEEDS CLARIFICATION: Which metrics?]
- Users can access dashboard [NEEDS CLARIFICATION: Access control model?]

After (spec.md):

## Requirements
- Dashboard displays:
  - Lesson completion rate (% of assigned lessons finished)
  - Time spent per lesson (hours logged)
  - Last activity date (to detect stale/inactive students)
- User access control (role-based):
  - Teachers: View assigned students only
  - Admins: View all students
  - Parents: View own children only (read-only)
  - Students: View own progress only

## Clarifications (Resolved)

### Q1: Dashboard Metrics Scope
**Asked**: Which metrics should the dashboard display?
**Options**: A) Completion only, B) Completion + time, C) Full analytics
**Decision**: Option B - Completion rate + time spent + last activity date
**Rationale**: Balances insights with implementation cost (4 days vs 7 for full analytics)
**Additional**: Last activity date added for staleness detection

### Q2: User Access Control
**Asked**: What access control model should be used?
**Options**: A) Simple (users/admins), B) Standard CRUD, C) Role-based
**Decision**: Option C - Role-based access control
**Rationale**: Future-proof for additional roles (e.g., counselors, district admins)
**Additional**: Parent role added with read-only access to children's data

### Deferred Assumptions - Overrides
**Rate Limiting**: Changed from 100/min to 200/min (power users on platform)

Quality check: All [NEEDS CLARIFICATION] markers removed, decisions documented.

Step 8: Validate Integration

Actions:

1. Run checks:

   bashCopy

   # Verify no markers remain
   REMAINING=$(grep -c "\[NEEDS CLARIFICATION" specs/NNN-slug/spec.md)
   if [ $REMAINING -gt 0 ]; then
     echo "⚠️  Still has $REMAINING unresolved clarifications"
     grep -n "\[NEEDS CLARIFICATION" specs/NNN-slug/spec.md
     exit 1
   fi
   
   # Verify clarifications section added
   if ! grep -q "## Clarifications (Resolved)" specs/NNN-slug/spec.md; then
     echo "⚠️  Missing Clarifications section in spec.md"
     exit 1
   fi
   

2. Review spec.md for completeness:

   • All requirements now concrete (no ambiguities)
   • Decisions documented with rationale
   • Ready for planning phase

Quality check: spec.md is complete and unambiguous.

Step 9: Commit Clarifications

Actions:

git add specs/NNN-slug/clarifications.md specs/NNN-slug/spec.md
git commit -m "docs: resolve clarifications for <feature-name>

Answered 2 critical questions:
- Dashboard metrics scope: Completion + time + last activity (Option B)
- User access control: Role-based (Option C) + Parent role

Deferred assumptions:
- Export format: CSV (standard)
- Rate limiting: 200/min (override: power users)
- Cache duration: 10 min (standard)

All [NEEDS CLARIFICATION] markers removed from spec.md
Ready for planning phase
"

Quality check: Clarifications committed, workflow-state.yaml updated.

Common Mistakes to Avoid

🚫 Too Many Clarification Questions (>3)

Impact: Delays workflow, frustrates users, analysis paralysis

Scenario:

Generated 7 questions for simple feature:
1. What format for export? (CSV/JSON) → Has default (CSV)
2. Which fields to include? → Critical, should ask
3. Email notification? → Has default (optional)
4. Rate limiting? → Has default (100/min)
5. Max file size? → Has default (50MB)
6. Retention period? → Has default (90 days)
7. Compress files? → Has default (yes for >10MB)

Prevention:

• Apply prioritization matrix strictly
• Keep only Critical + High priority
• Convert Medium/Low to informed guesses
• Target: ≤3 questions

🚫 Vague or Compound Questions

Impact: Unclear answers, requires follow-up, wastes time

Bad examples:

❌ "What features should the dashboard have and how should it look?"
   (Compound: mixes functionality + design)

❌ "What should we do about errors?"
   (Too vague: no context, no options)

❌ "Do you want this to be good?"
   (Subjective, not actionable)

Good examples:

✅ Question 1: Dashboard Metrics Scope
   Context: spec mentions "progress" but not which metrics
   Options: A) Completion only, B) Completion + time, C) Full analytics
   Impact: [quantified costs]
   Recommendation: Option B

✅ Question 2: Error Handling Strategy
   Context: Spec doesn't specify how to handle API failures
   Options: A) Retry 3x then fail, B) Retry indefinitely, C) Circuit breaker
   Impact: [quantified costs + user experience]
   Recommendation: Option A

Prevention: Use structured template (Context → Options → Impact → Recommendation)

🚫 Missing Spec Integration

Impact: Clarifications not reflected in spec, planning phase lacks context

Scenario:

User answered 3 clarifications but:
- spec.md still says "[NEEDS CLARIFICATION: Dashboard scope]"
- plan.md can't proceed without knowing scope
- Implementation phase guesses requirements

Prevention:

1. Update spec.md Requirements section with concrete details
2. Remove all [NEEDS CLARIFICATION] markers
3. Add "Clarifications (Resolved)" section
4. Run validation check before completing phase

Validation:

# Must return 0
grep -c "\[NEEDS CLARIFICATION" specs/NNN-slug/spec.md

🚫 No Deferred Assumptions Documented

Impact: User doesn't know what defaults were applied

Prevention: Document all Medium/Low priority questions as assumptions with rationale

🚫 Questions Without Options

Impact: Open-ended answers, hard to integrate into spec

Bad example:

❌ Question 1: What should the dashboard show?
   (No options, completely open-ended)

Good example:

✅ Question 1: Dashboard Metrics Scope
   Options: A, B, C (concrete choices with costs)

Prevention: Always provide 2-3 concrete options with quantified impacts

Best Practices

✅ Structured Question Format

Template:

## Question N: [Short Title]

**Context**: [Explain ambiguity + spec reference]

**Options**:
A. [Concrete option 1]
B. [Concrete option 2]
C. [Concrete option 3]

**Impact**:
- Option A: [Cost + value + tradeoffs]
- Option B: [Cost + value + tradeoffs]
- Option C: [Cost + value + tradeoffs]

**Recommendation**: [Suggested option + rationale]

**References**: [spec.md line number]

Result: Clear answers, faster decisions, easy spec integration

✅ Prioritized Question List

Approach:

1. Categorize: Critical, High, Medium, Low
2. Ask: Critical + High only
3. Document: Medium + Low as assumptions

Example:

## Questions (Critical + High Priority)
1. Dashboard scope (Critical)
2. Access control model (High)

## Deferred Assumptions (Medium + Low Priority)
- Export format: CSV (Low - standard default)
- Rate limit: 100/min (Low - reasonable default)
- Refresh rate: 5 min (Medium - standard default)

Result: Focused user attention, faster responses, reasonable defaults

✅ Clarification Response Integration Checklist

After receiving answers:

• Update spec.md Requirements with concrete details
• Remove all [NEEDS CLARIFICATION] markers
• Add "Clarifications (Resolved)" section
• Document rationale for each decision
• Include additional context from user
• Verify grep "\[NEEDS CLARIFICATION" spec.md returns nothing
• Commit with descriptive message

Phase Checklist

Pre-phase checks:

• spec.md has [NEEDS CLARIFICATION] markers (otherwise skip)
• Clarification count ≤5 (if >5, review spec phase)
• Git working tree clean

During phase:

• Questions prioritized (Critical, High, Medium, Low)
• Only Critical + High questions asked (target: ≤3)
• Questions follow structured format (Context → Options → Impact)
• Deferred questions documented as assumptions
• User provided answers to all questions

Post-phase validation:

• spec.md Requirements updated with concrete details
• All [NEEDS CLARIFICATION] markers removed
• "Clarifications (Resolved)" section added to spec.md
• Deferred assumptions documented
• Clarifications committed
• workflow-state.yaml updated

Quality Standards

Clarification quality targets:

• Question count: ≤3 per feature
• Question clarity: All follow structured format
• Response integration: 100% (no remaining markers)
• Time to resolution: ≤2 hours (user response time varies)
• Follow-up questions: <10%

What makes good clarifications:

• ≤3 questions (prioritized rigorously)
• Structured format (Context → Options → Impact)
• Concrete options (2-3 specific choices, not open-ended)
• Quantified impacts (implementation costs + user value)
• Clear recommendations (suggested option with rationale)
• Complete integration (all markers removed from spec)

What makes bad clarifications:

• 5 questions (didn't prioritize)

• Vague questions ("What should we do?")
• Compound questions (mixing multiple decisions)
• No options (open-ended)
• Missing integration (markers remain in spec)

Completion Criteria

Phase is complete when:

• All pre-phase checks passed
• All questions answered by user
• spec.md updated with concrete requirements
• All [NEEDS CLARIFICATION] markers removed
• Clarifications committed
• workflow-state.yaml shows currentPhase: clarification and status: completed

Ready to proceed to next phase (/plan):

• spec.md is complete and unambiguous
• All decisions documented with rationale
• No remaining ambiguities

Troubleshooting

Issue: Too many questions (>3) Solution: Apply prioritization matrix more strictly, convert Medium/Low to assumptions

Issue: Questions are vague Solution: Use structured template (Context → Options → Impact), provide 2-3 concrete options

Issue: User can't choose between options Solution: Add more context about tradeoffs, strengthen recommendation with rationale

Issue: [NEEDS CLARIFICATION] markers remain after integration Solution: Review each marker, update spec.md with concrete details, run validation check

Issue: Planning phase blocked due to ambiguity Solution: spec integration was incomplete, return to /clarify and complete integration

This SOP guides the clarification phase. Refer to reference.md for prioritization details and examples.md for question patterns.