Quiz Generator

Quick Start

1. Generate 50 questions for chapter

Focus on conceptual (75%+ Apply level), not recall

2. Redistribute answers evenly

python scripts/redistribute_answers_v2.py quiz.md A

3. Validate option lengths (±3 words per question)

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

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

Analysis Questions

1. Is this conceptual (not recall)?

Type Example Valid?

Recall "What is a Python list?" ❌

Conceptual "Which operation reveals a mutability issue?" ✅

Target: 75%+ at Apply level or higher

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

Options Words Valid?

A: "Yes" / B: "It processes async" 2 vs 4 ✅

A: "Yes" / B: "The framework processes requests asynchronously" 2 vs 6 ❌

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

3. Are answers evenly distributed?

Index Count Valid?

0 12-13 ✅

1 12-13 ✅

2 12-13 ✅

3 12-13 ✅

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:

• Why correct is correct (2-3 sentences)

• Why each distractor is wrong (1-2 sentences × 3)

• Real-world connection (1-2 sentences)

Principle 4: Source Attribution

source: "Lesson 1: Understanding Mutability"

Links each question to specific lesson for review.

Quiz Component Format

sidebar_position: 5 title: "Chapter X: [Topic] Quiz"

Chapter X Quiz

Brief intro (1-2 sentences).

<Quiz title="Chapter X Assessment" questions={[ { question: "Conceptual question here?", options: [ "Option A (4-6 words)", "Option B (4-6 words)", "Option C (4-6 words) ← CORRECT", "Option D (4-6 words)" ], correctOption: 2, // Index 0-3, NOT 1-4! 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.", source: "Lesson 1: Topic Title" }, // ... 49 more questions (total: 50) ]} questionsPerBatch={18} />

Answer Redistribution

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

python scripts/redistribute_answers_v2.py quiz.md A

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

What it does:

• Parses quiz questions

• Swaps option positions to match sequence

• Updates explanations to reference new positions

• 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

Pitfall Wrong Right

Question count <50 questions Exactly 50

Index values correctOption: 4

correctOption: 3 (0-3)

Missing source No source field source: "Lesson N: Title"

Passing score passingScore={70}

No prop (removed)

Recall questions "What is X?" "Which reveals X issue?"

Weak explanations Only explains correct Addresses all 4 options

Answer patterns 0,1,2,3,0,1,2,3... Random, ~12-13 per index

Option lengths 2 vs 11 words All within ±3 words

File Naming

Pattern: ##chapter##_quiz.md

Chapter Lessons Filename

2 4 05_chapter_02_quiz.md

5 6 07_chapter_05_quiz.md

14 5 06_chapter_14_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

• Run redistribution script: python scripts/redistribute_answers_v2.py quiz.md A

• Re-count option lengths manually

• Check explanation references match correctOption

• Stop and report if issues persist after 2 attempts