quiz

# Quiz — Interactive Knowledge Testing

**ALWAYS** use the `AskUserQuestion` tool when asking the user questions, in any context. If you have too many questions for the tool, split them up into multiple calls.

Generate and deliver mixed-format quiz questions based on the user's learning plan. Ask one question at a time, give immediate feedback, track scores, and adapt difficulty based on prior performance.

## File Storage Rules — EXACT PATHS (no deviation)

Quiz progress is saved to ONE specific directory:

    ~/.claude/learning/progress/{topic-slug}.json

CORRECT path for quiz progress: `~/.claude/learning/progress/dns.json`
WRONG path for quiz progress:   `~/.claude/learning/plans/dns-2026-03-29.json`

CORRECT — saving any learning data: `~/.claude/learning/progress/dns.json`
WRONG — saving to project directory: `./learning/progress/dns.json`

Always use the ABSOLUTE path `~/.claude/learning/` — never a relative path like `./learning/`.
Never write quiz data (quizzes, weakAreas, strongAreas, spacedRepetition, overallScore) to plan files.
Never add extra fields beyond those defined in Step 6's schema.
Verify the path contains `/progress/` before writing.

## Process

### Step 1: Determine Topic & Module

**If the user specified a topic** (e.g., `/quiz kubernetes`):
- Read `~/.claude/learning/index.json`
- Find matching topic (fuzzy match: "k8s" → "kubernetes", "Spanish" → "spanish-grammar")
- If ambiguous, ask the user to clarify

**If no topic specified** (just `/quiz`):
- Read index.json, find topic with most recent `lastActivity`
- Confirm with user: "Quiz you on [topic]?"

**If no learning plans exist:**
- Tell the user: "No learning plans found. Use /learn <topic> to create one first, or tell me a topic and I'll quiz you on general knowledge."
- If user provides a topic without a plan, generate questions from Claude's knowledge (no plan file needed)

**Module targeting:**
- If user says "test me on module 2" or "quiz me on deployments", target that specific module
- Otherwise, quiz across all modules, weighting toward weak areas if prior quiz data exists

### Step 2: Load Prior Performance

You MUST read `~/.claude/learning/progress/[topic-slug].json` before generating questions. This file contains quiz history, weak/strong areas, and spaced repetition schedules. If you skip this step, the quiz won't adapt to the user's level.

**Adaptive difficulty — mention your adjustments to the user:**
- No prior data → generate questions at the plan's level
- Prior overall score > 80% → tell the user "Your score is high, so I'm asking harder, more conceptual questions" and increase difficulty
- Prior overall score < 50% → tell the user "Let's focus on the fundamentals" and decrease difficulty
- Weight questions toward `weakAreas` from prior quizzes
- If `spacedRepetition` data exists, check for concepts where `nextReview` is today or in the past. These are overdue for review — tell the user "You have N concepts due for review" and include them in the quiz

### Step 3: Generate Questions

Generate a set of questions (default: 5, user can request more/fewer).

**Mix of formats:**

| Format | Use for | Proportion |
|---|---|---|
| **Multiple choice** (4 options, one correct) | Factual recall, terminology, definitions | ~40% |
| **True/False** | Common misconceptions, nuanced distinctions | ~20% |
| **Short answer** (1-3 sentences) | Conceptual understanding, explanations | ~25% |
| **Fill-in-the-blank** | Syntax, commands, formulas, key terms | ~15% |

**Question quality rules:**
- Questions should test understanding, not trick the user
- Wrong MCQ options should be plausible (common misconceptions), not obviously wrong
- Short answer questions should have clear evaluation criteria (key concepts to look for)
- Each question should map to a specific concept from the learning plan

### Step 4: Deliver Interactively

Ask ONE question per message. Use multiple choice with clear options and descriptions for every question. Wait for the user's answer before proceeding to the next.

**Question format examples:**

Multiple choice — "Q1/5 (Multiple Choice) — Which Kubernetes object ensures a specified number of pod replicas are running?" with 4 options, each with a short description.

True/False — "Q2/5 (True or False) — In TCP, the receiver sends acknowledgments for every individual packet." with True/False options, each with a clarifying description.

Fill-in-the-blank — "Q3/5 (Fill in the Blank) — The kubectl command to view all running pods is: kubectl _____ pods -n <namespace>" with 4 options.

Short answer — "Q4/5 (Short Answer) — Explain the difference between a Pod and a Deployment. Pick the closest answer." with 2-3 options plus "Other (None of these match my understanding)".

**After the user answers, give feedback:**

If correct:
> Correct! [1-2 sentence explanation reinforcing the concept]

If incorrect:
> Not quite. The answer is [correct answer]. [2-3 sentence explanation helping the user understand]

For short answers, evaluate for key concepts, not exact wording. If partially correct, say what they got right and what's missing. Be encouraging but honest.

Then immediately ask the next question — no extra text between feedback and the next question.

### Step 5: Show Results

After all questions, present a summary:

```
── Results: [Topic] ──────────────────────
Score: [correct]/[total] ([percentage]%)

[For each question:]
[✓/✗] Q[n]: [brief concept label]

[If there are wrong answers:]
Weak areas: [list concepts that need review]
Suggestion: [specific actionable advice]
──────────────────────────────────────────
```

### Step 6: Save Progress

The progress file at `~/.claude/learning/progress/{topic-slug}.json` is the **single source of truth** for quiz data. The web dashboard also reads and writes this file. Always read the existing file first, then append/update — never overwrite from scratch.

1. **Construct path**: `~/.claude/learning/progress/{topic-slug}.json`
2. **Verify path*