clarification-phase

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:

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

Update spec.md:

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

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

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

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

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

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

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 ❌

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)

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)",
        },
      ],
    },
  ],
});

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

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

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" },
      ],
    },
  ],
});