clarification-phase

<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:

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>

<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:

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

Example:

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

Update spec.md:

```markdown
<!-- Before -->

Dashboard displays student progress [NEEDS CLARIFICATION: Whi