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 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 " 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 contains /progress/ — NOT /plans/
3. Create directory ~/.claude/learning/progress/ if it doesn't exist
4. Read the existing file — if it exists, load its current data and append to it. If it doesn't exist, create a new object
5. Append the new quiz to the quizzes array (do not replace existing quizzes)
6. Recompute weakAreas, strongAreas, and overallScore from ALL quizzes (not just the latest)
7. Update spacedRepetition for each concept tested
8. Write the file using ONLY the fields listed below — no extra fields:

{
  "topic": "topic-slug",
  "quizzes": [
    {
      "date": "YYYY-MM-DD",
      "module": null,
      "score": 4,
      "total": 5,
      "difficulty": "beginner",
      "questions": [
        {
          "format": "mcq",
          "concept": "concept-label",
          "correct": true
        }
      ]
    }
  ],
  "weakAreas": ["concept-a", "concept-b"],
  "strongAreas": ["concept-c", "concept-d"],
  "overallScore": 80
}

CRITICAL format rules — the web dashboard reads these files, so the format must be exact:

• overallScore is a percentage (0-100), NOT a fraction. 80 not 0.8.
• weakAreas and strongAreas are arrays of strings (concept names), NOT objects.
  • CORRECT: "weakAreas": ["DNS resolution", "CNAME records"]
  • WRONG: "weakAreas": [{"concept": "DNS resolution", "moduleId": 1}]
• spacedRepetition keys must be concept names (matching the concept field in questions), NOT module IDs.
  • CORRECT: "spacedRepetition": {"DNS resolution": {...}}
  • WRONG: "spacedRepetition": {"1": {...}, "2": {...}}
• All spacedRepetition values must have easeFactor (number), intervalDays (integer), nextReview (YYYY-MM-DD string), repetitions (integer). None can be null.

Compute weak/strong areas (aggregate across ALL quizzes):

• For each concept that has ever appeared in any quiz question, count total attempts and correct answers
• Concepts correct in <50% of attempts → weakAreas (as plain strings)
• Concepts correct in >=80% of attempts → strongAreas (as plain strings)
• overallScore = round(total correct across all quizzes / total questions across all quizzes × 100)

Update spaced repetition schedule:

For each concept tested in this quiz, update the spacedRepetition field in the progress file using the SM-2 algorithm:

For each concept:

1. Determine quality score (0-5): correct on first try = 5, correct after hesitation = 4, incorrect but close = 2, incorrect = 0
2. If quality >= 3 (correct):
   • If first review (repetitions was 0): intervalDays = 1
   • If second review (repetitions was 1): intervalDays = 6
   • Subsequent: intervalDays = round(previous interval × easeFactor)
   • repetitions += 1
3. If quality < 3 (incorrect):
   • Reset: intervalDays = 1, repetitions = 0
4. Update ease factor: easeFactor = max(1.3, easeFactor + 0.1 - (5 - quality) × (0.08 + (5 - quality) × 0.02))
5. Compute nextReview = today + intervalDays (format: YYYY-MM-DD)

For new concepts (not yet in spacedRepetition), initialize with easeFactor: 2.5, intervalDays: 1, repetitions: 0, nextReview: today + 1 day.

Validation before writing: Every SR entry must have all 4 fields set to non-null values. If any field would be null, use the default: easeFactor: 2.5, intervalDays: 1, repetitions: 0, nextReview: tomorrow.

Updated progress JSON structure:

{
  "topic": "topic-slug",
  "quizzes": [...],
  "weakAreas": [...],
  "strongAreas": [...],
  "overallScore": 80,
  "spacedRepetition": {
    "concept-label": {
      "easeFactor": 2.5,
      "intervalDays": 6,
      "nextReview": "2026-03-26",
      "repetitions": 2
    }
  }
}

This is backwards-compatible — if spacedRepetition is missing, treat all concepts as unscheduled.

9. Update index.json at ~/.claude/learning/index.json:
   • Read existing index first
   • Set topics[slug].quizzesTaken = total number of quizzes in the progress file
   • Set topics[slug].overallScore = the computed overallScore (percentage, 0-100)
   • Set topics[slug].lastActivity = today's date (YYYY-MM-DD)

No-Plan Quiz Mode

If a user asks to be quizzed on a topic with no existing learning plan:

• Generate questions from Claude's own knowledge
• Still deliver interactively with feedback
• Still save progress to enable tracking
• Suggest: "Want me to create a full learning plan for this topic? Use /learn [topic]"