<objective> Execute the /clarify phase by resolving critical ambiguities in spec.md through structured questioning (≤3 questions), prioritization, and answer integration. Ensures specifications are concrete and unambiguous before planning phase. </objective>

<quick_start> Resolve ambiguities in spec.md using AskUserQuestion tool:

•Extract [NEEDS CLARIFICATION] markers from spec.md
•Prioritize using matrix (Critical/High → ask, Medium/Low → assumptions)
•Call AskUserQuestion with ≤3 questions (batched, multiSelect for subsystems)
•Receive user answers synchronously
•Integrate into spec.md, remove all markers
•Add Clarifications (Resolved) section with deferred assumptions

Inputs: spec.md with [NEEDS CLARIFICATION] markers Outputs: Updated spec.md (no markers), clarifications.md (record) </quick_start>

<prerequisites> - Spec phase completed (spec.md exists) - spec.md contains ≥1 [NEEDS CLARIFICATION] marker (if none, skip /clarify) - Git working tree clean

If clarification count >5, review spec phase quality (too many ambiguities). </prerequisites>

<workflow> <step number="1"> **Extract clarification needs**

Read spec.md, find all [NEEDS CLARIFICATION: ...] markers, extract ambiguity context.

bash

# Count clarifications
grep -c "\[NEEDS CLARIFICATION" specs/NNN-slug/spec.md

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

If count = 0, skip /clarify phase. </step>

<step number="2"> **Prioritize questions**

Categorize each clarification by priority:

•Critical (always ask): Scope boundary, security/privacy, breaking changes
•High (ask if ambiguous): User experience decisions, functionality tradeoffs
•Medium (use defaults): Performance SLAs, technical stack choices
•Low (use standards): Error messages, rate limits

Keep only Critical + High priority questions (target: ≤3).

Convert Medium/Low to informed guesses, document as assumptions.

See references/prioritization-matrix.md for detailed categorization rules. </step>

<step number="3"> **Prepare AskUserQuestion tool call**

For each Critical/High priority clarification, structure as AskUserQuestion parameter:

AskUserQuestion format:

javascript

AskUserQuestion({
  questions: [
    {
      question:
        "spec.md:45 mentions 'dashboard metrics' but doesn't specify which. What should we display?",
      header: "Metrics", // max 12 chars
      multiSelect: false,
      options: [
        {
          label: "Completion only",
          description: "% of lessons finished (2 days, basic insights)",
        },
        {
          label: "Completion + time",
          description:
            "Lessons finished + hours logged (4 days, actionable insights)",
        },
        {
          label: "Full analytics",
          description:
            "Completion + time + quiz scores + engagement (7 days, requires infrastructure)",
        },
      ],
    },
  ],
});

Quality standards:

•question: Full context with spec.md reference (e.g., "spec.md:45 mentions...")
•header: Short label ≤12 chars (e.g., "Metrics", "Auth", "Scope")
•multiSelect: false for single choice, true for subsystems/features
•options: 2-3 concrete choices with impacts in description
•label: Concise option name (1-5 words)
•description: Implementation cost + value + tradeoffs (1-2 sentences)

Batch related questions (max 3 per AskUserQuestion call).

See references/question-bank.md for 40+ example questions in AskUserQuestion format. </step>

<step number="4"> **Document deferred assumptions**

For Medium/Low priority questions not asked, prepare assumptions section:

markdown

## Deferred Assumptions (Using Informed Guesses)

### [Topic]

**Not asked** (Low priority - standard default exists)
**Assumption**: [Concrete default choice]
**Rationale**: [Why this default is reasonable]
**Override**: [How user can override in spec.md]

These will be included in clarifications.md record after AskUserQuestion call. </step>

<step number="5"> **Call AskUserQuestion tool**

Execute AskUserQuestion with batched Critical/High questions:

javascript

AskUserQuestion({
  questions: [
    {
      question:
        "spec.md:45 mentions 'dashboard metrics'. Which should we display?",
      header: "Metrics",
      multiSelect: false,
      options: [
        { label: "Completion only", description: "2 days, basic insights" },
        {
          label: "Completion + time",
          description: "4 days, actionable insights",
        },
        {
          label: "Full analytics",
          description: "7 days, requires infrastructure",
        },
      ],
    },
    {
      question:
        "spec.md:67 doesn't specify access control model. Which approach?",
      header: "Access",
      multiSelect: false,
      options: [
        {
          label: "Simple (users/admins)",
          description: "2 days, basic permissions",
        },
        {
          label: "Role-based (RBAC)",
          description: "4 days, flexible permissions",
        },
      ],
    },
  ],
});

Batching strategy:

•Batch 2-3 related questions per call
•Use multiSelect: true for subsystem/feature selection questions
•Use multiSelect: false for single-choice decisions

Tool returns answers object:

javascript

{
  "Metrics": "Completion + time",
  "Access": "Role-based (RBAC)"
}

User can also select "Other" for custom answers. </step>

<step number="6"> **Integrate answers into spec.md**

Use answers from AskUserQuestion tool response to update spec:

For each answered question:

•Locate corresponding [NEEDS CLARIFICATION] marker in spec.md
•Replace with concrete requirement based on selected option
•Remove marker

Example:

javascript

// AskUserQuestion returned:
{
  "Metrics": "Completion + time",
  "Access": "Role-based (RBAC)"
}

Update spec.md:

markdown

<!-- Before -->

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

<!-- After -->

Dashboard displays:

- Lesson completion rate (% of assigned lessons finished)
- Time spent per lesson (hours logged)

User access control (role-based):

- Teachers: View assigned students only
- Admins: View all students
- Students: View own progress only

Validate integration:

bash

# Must return 0 (no markers remain)
grep -c "\[NEEDS CLARIFICATION" specs/NNN-slug/spec.md

</step> <step number="7"> **Create clarifications.md record**

Generate specs/NNN-slug/clarifications.md as historical record:

markdown

# Clarifications for [Feature Name]

**Date**: [timestamp]
**Questions Asked**: 2 (Critical: 1, High: 1)
**Deferred**: 3 assumptions

## Questions & Answers

### Q1: Dashboard Metrics (Critical)

**Question**: spec.md:45 mentions 'dashboard metrics'. Which should we display?
**Options**: Completion only | Completion + time | Full analytics
**Selected**: Completion + time
**Rationale**: Balances actionable insights with implementation cost (4 days vs 7)

### Q2: Access Control (High)

**Question**: spec.md:67 doesn't specify access control model. Which approach?
**Options**: Simple (users/admins) | Role-based (RBAC)
**Selected**: Role-based (RBAC)
**Rationale**: Future-proof for additional roles

## Deferred Assumptions

### Export Format (Low)

**Not asked** - Standard default exists
**Assumption**: CSV format
**Rationale**: Most compatible, industry standard
**Override**: Specify in spec.md if JSON/Excel needed

### Rate Limiting (Low)

**Not asked** - Reasonable default
**Assumption**: 100 requests/minute per user
**Rationale**: Conservative, prevents abuse
**Override**: Specify in spec.md if higher limits needed

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

markdown

## Clarifications (Resolved)

Answered 2 questions on [date]:

1. Dashboard metrics: Completion + time spent (4 days)
2. Access control: Role-based RBAC (future-proof)

Deferred assumptions: Export format (CSV), Rate limiting (100/min)

See clarifications.md for full details.

</step> <step number="8"> **Commit clarifications**

bash

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

Answered N questions:
- [Q1 summary]: [Decision]
- [Q2 summary]: [Decision]

Deferred assumptions:
- [Topic]: [Choice] ([reason])

All [NEEDS CLARIFICATION] markers removed
Ready for planning phase"

Update state.yaml: clarification.status = completed </step> </workflow>

<validation> After clarification phase, verify:

•All [NEEDS CLARIFICATION] markers removed from spec.md
•≤3 structured questions asked (Critical + High only)
•Medium/Low priorities documented as assumptions
•Answers integrated into spec.md Requirements section
•Clarifications (Resolved) section added to spec.md
•clarifications.md generated with user answers
•state.yaml updated (clarification.status = completed)
•Git commit created with descriptive message </validation>

<anti_patterns> <pitfall name="too_many_questions"> ❌ Don't: Ask >3 questions per feature (7+ questions for simple feature) ✅ Do: Apply prioritization matrix strictly, keep only Critical/High, convert Medium/Low to assumptions

Why: Delays workflow, frustrates users, causes analysis paralysis Target: ≤3 questions total after prioritization

Example (bad):

code

7 questions for export feature:
1. Export format? (CSV/JSON) → Has default ❌
2. Which fields? → Critical ✅
3. Email notification? → Has default ❌
4. Rate limiting? → Has default ❌
5. Max file size? → Has default ❌
6. Retention period? → Has default ❌
7. Compress files? → Has default ❌

Should be:

code

1 question (Critical):
- Which fields to export? (no reasonable default)

6 deferred assumptions:
- Format: CSV (standard)
- Email: Optional (user preference)
- Rate limit: 100/min (reasonable)
- Max size: 50MB (standard)
- Retention: 90 days (compliance standard)
- Compression: Auto >10MB (performance)

</pitfall> <pitfall name="vague_compound_questions"> **❌ Don't**: Ask vague or compound questions - "What features should dashboard have and how should it look?" (compound - mixes features + design) - "What should we do about errors?" (too vague, no context, no options) - "Do you want this to be good?" (subjective, not actionable)

✅ Do: Use AskUserQuestion with clear context, 2-3 concrete options, quantified impacts

Why: Unclear questions lead to ambiguous answers, require follow-up, waste time

Example (good with AskUserQuestion):

javascript

AskUserQuestion({
  questions: [
    {
      question:
        "spec.md:45 mentions 'progress' but doesn't specify which metrics to display. What should the dashboard show?",
      header: "Metrics",
      multiSelect: false,
      options: [
        {
          label: "Completion only",
          description: "% of lessons finished (2 days, basic insights)",
        },
        {
          label: "Completion + time",
          description:
            "Lessons finished + hours logged (4 days, actionable insights for identifying struggling students)",
        },
        {
          label: "Full analytics",
          description:
            "Completion + time + quiz scores + engagement (7 days, requires analytics infrastructure)",
        },
      ],
    },
  ],
});

Result: Clear, specific options with quantified impacts - user can make informed decision. </pitfall>

<pitfall name="missing_spec_integration"> **❌ Don't**: Leave clarifications in separate file without updating spec.md **✅ Do**: Integrate all answers into spec.md Requirements, remove all [NEEDS CLARIFICATION] markers

Why: Planning phase can't proceed without concrete requirements in spec

Validation:

bash

# Must return 0 (no markers remain)
grep -c "\[NEEDS CLARIFICATION" specs/NNN-slug/spec.md

</pitfall> <pitfall name="no_deferred_assumptions"> **❌ Don't**: Skip documenting Medium/Low questions **✅ Do**: Document all Medium/Low as assumptions with rationale in clarifications.md

Why: User doesn't know what defaults were applied, can't override if needed

Example:

markdown

## Deferred Assumptions

### Rate Limiting

**Not asked** (Low priority - reasonable default)
**Assumption**: 100 requests/minute per user
**Rationale**: Prevents abuse, can increase based on usage
**Override**: Specify in spec.md if higher limits needed

</pitfall> <pitfall name="questions_without_options"> **❌ Don't**: Ask open-ended questions without concrete options - "What should the dashboard show?" (completely open)

✅ Do: Provide 2-3 concrete options with quantified impacts

•Options: A/B/C with implementation costs + user value

Why: Open-ended answers are hard to integrate into spec, lead to follow-up questions </pitfall> </anti_patterns>

<best_practices> <practice name="structured_format"> Always use AskUserQuestion tool with structured format:

•question: Full context with spec.md reference (e.g., "spec.md:45 mentions...")
•header: Short label ≤12 chars (e.g., "Metrics", "Auth")
•options: 2-3 concrete choices with implementation costs in description
•multiSelect: false for single choice, true for subsystems/features

Example:

javascript

AskUserQuestion({
  questions: [
    {
      question: "spec.md:45 mentions 'metrics'. What should we display?",
      header: "Metrics",
      multiSelect: false,
      options: [
        { label: "Completion only", description: "2 days, basic" },
        { label: "Completion + time", description: "4 days, actionable" },
        { label: "Full analytics", description: "7 days, complex" },
      ],
    },
  ],
});

Result: Clear answers, faster decisions, easy spec integration </practice>

<practice name="prioritized_list"> Categorize all clarifications: 1. Critical → Ask always 2. High → Ask if ambiguous 3. Medium → Document as assumption 4. Low → Document as assumption

Target: ≤3 questions (Critical + High only)

Result: Focused user attention, faster responses, reasonable defaults </practice>

<practice name="integration_checklist"> After receiving answers from AskUserQuestion: - [ ] Extract selected options from tool response (answers object) - [ ] Update spec.md Requirements with concrete details based on selections - [ ] Remove all [NEEDS CLARIFICATION] markers - [ ] Create clarifications.md record with questions + answers - [ ] Add "Clarifications (Resolved)" section to spec.md - [ ] Document deferred assumptions in clarifications.md - [ ] Verify `grep "\[NEEDS CLARIFICATION" spec.md` returns 0 - [ ] Commit with descriptive message

Result: Complete spec, ready for planning phase </practice> </best_practices>

<success_criteria> Phase complete when:

<quality_standards> Targets:

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

Good clarifications:

•≤3 questions (rigorously prioritized)
•Structured format (Context → Options → Impact → Recommendation)
•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)

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) </quality_standards>

<troubleshooting> **Issue**: Too many questions (>3) **Solution**: Apply prioritization matrix strictly, convert Medium/Low to assumptions, batch related questions

Issue: Questions are vague Solution: Use AskUserQuestion format with clear context + spec reference, 2-3 concrete options, quantified impacts in description

Issue: User can't choose between options Solution: Add more context to question text, include cost/benefit tradeoffs in option descriptions

Issue: AskUserQuestion header too long Solution: Keep header ≤12 chars (e.g., "Metrics" not "Dashboard Metrics Scope")

Issue: [NEEDS CLARIFICATION] markers remain after integration Solution: Extract answers from AskUserQuestion response, update spec.md for each marker, run validation check

Issue: Planning phase blocked due to ambiguity Solution: Spec integration incomplete, verify answers mapped to spec requirements correctly </troubleshooting>

<references> See references/ for: - Prioritization matrix (Critical/High/Medium/Low categorization rules) - Question bank (40+ example questions in AskUserQuestion format) - Execution workflow (detailed step-by-step with bash commands) - Question quality examples (good vs bad questions with AskUserQuestion)

See templates/ for:

•clarification-template.md (clarifications.md record template) </references>