clarification-phase

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

1. Extract [NEEDS CLARIFICATION] markers from spec.md
2. Prioritize using matrix (Critical/High → ask, Medium/Low → assumptions)
3. Call AskUserQuestion with ≤3 questions (batched, multiSelect for subsystems)
4. Receive user answers synchronously
5. Integrate into spec.md, remove all markers
6. 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>

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

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

# 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.

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.

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

AskUserQuestion format:

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.

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

## 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.