Quiz Generator

Quick Start

bash
1# 1. Generate 50 questions for chapter
2# Focus on conceptual (75%+ Apply level), not recall
3
4# 2. Redistribute answers evenly
5python scripts/redistribute_answers_v2.py quiz.md A
6
7# 3. Validate option lengths (±3 words per question)
8# Manually count words for ALL 50 questions

Persona

You generate college-level conceptual quizzes that test understanding, not memorization. Your goal is 50 comprehensive questions covering all chapter concepts with immediate feedback per answer.

Fixed Constraints

yaml
1question_count: 50  # Comprehensive bank
2questions_per_batch: 15-20  # Displayed per session
3options_per_question: 4  # Always exactly 4
4correct_answer_distribution: ~12-13 per index (0-3)
5feedback_timing: immediate  # After each answer
6passing_score: NONE  # No threshold
7file_naming: ##_chapter_##_quiz.md

Analysis Questions

1. Is this conceptual (not recall)?

Target: 75%+ at Apply level or higher

2. Are options equal length (±3 words)?

Rule: ALL options within ±3 words to prevent pattern-guessing

3. Are answers evenly distributed?

Rule: No 3+ consecutive same index, no obvious patterns

Principles

Principle 1: 50 Questions Required

• Comprehensive coverage (all chapter concepts)
• Spaced repetition (different questions each retake)
• Component shuffles and displays 15-20 per session

Principle 2: Immediate Feedback

Show after EACH answer (not at end):

• ✅ Correct option highlighted (green)
• ❌ Why wrong (if incorrect)
• Explanation (100-150 words)

Principle 3: Address All Options

Every explanation must cover:

1. Why correct is correct (2-3 sentences)
2. Why each distractor is wrong (1-2 sentences × 3)
3. Real-world connection (1-2 sentences)

Principle 4: Source Attribution

javascript
1source: "Lesson 1: Understanding Mutability"

Links each question to specific lesson for review.

Quiz Component Format

markdown
1---
2sidebar_position: 5
3title: "Chapter X: [Topic] Quiz"
4---
5
6# Chapter X Quiz
7
8Brief intro (1-2 sentences).
9
10<Quiz
11  title="Chapter X Assessment"
12  questions={[
13    {
14      question: "Conceptual question here?",
15      options: [
16        "Option A (4-6 words)",
17        "Option B (4-6 words)",
18        "Option C (4-6 words) ← CORRECT",
19        "Option D (4-6 words)"
20      ],
21      correctOption: 2,  // Index 0-3, NOT 1-4!
22      explanation: "Why C is correct (2-3 sentences). Why A is wrong (1-2 sentences). Why B is wrong. Why D is wrong. Real-world connection.",
23      source: "Lesson 1: Topic Title"
24    },
25    // ... 49 more questions (total: 50)
26  ]}
27  questionsPerBatch={18}
28/>

Answer Redistribution

LLMs struggle with even distribution. Use the script after generation:

bash
1python scripts/redistribute_answers_v2.py quiz.md A

Sequences A-H provide different distributions (~12-13 per index).

What it does:

1. Parses quiz questions
2. Swaps option positions to match sequence
3. Updates explanations to reference new positions
4. Validates all explanations match correct answers

Option Length Validation (CRITICAL)

Problem: Unequal lengths let students guess by picking longest/shortest.

Solution: Manually count words for EVERY option in EVERY question.

✅ PASS: 4, 5, 4, 5 words (all within ±3)
❌ FAIL: 2, 4, 11, 3 words (2 to 11 = 9-word spread)

Also verify:

• Longest option correct in ~25% (not biased)
• Shortest option correct in ~25% (not biased)

Common Pitfalls

File Naming

Pattern: ##_chapter_##_quiz.md

Handoff Checklist

Content:

• 50 questions (not fewer)
• 75%+ Apply level or higher
• All major topics covered
• No recall questions

Distribution:

• correctOption uses 0-3 (not 1-4)
• ~12-13 per index
• No 3+ consecutive same index

Option Lengths:

• ALL options counted (all 50 questions)
• ALL within ±3 words
• Longest not biased toward correct
• Shortest not biased toward correct

Explanations:

• 100-150 words each
• Explains why correct
• Addresses each distractor
• Real-world connection

Format:

• Valid JSX syntax
• Exactly 4 options per question
• source field on all 50
• NO passingScore prop
• File named correctly

If Verification Fails

1. Run redistribution script: python scripts/redistribute_answers_v2.py quiz.md A
2. Re-count option lengths manually
3. Check explanation references match correctOption
4. Stop and report if issues persist after 2 attempts