Version: 5.0.0 | Consolidates: quiz-answer-redistributor v3.0.0 | Alignment: Constitution v3.1.2, Co-Learning Partnership, "Specs Are the New Syntax" | KEY FEATURES: 50 total questions, automated answer redistribution with intelligent explanation regeneration, 15-20 displayed per batch, immediate feedback per question, randomized batching on retake, no pass/fail threshold, evals-aligned questions
Quiz Component Location:book-source/src/components/Quiz.tsx (globally registered—no imports needed)
Usage Reference:book-source/src/components/QUIZ_USAGE.md (example structure + best practices)
Example Quiz:book-source/src/components/references/example-quiz.md (full working example with all patterns)
Purpose
Generate high-quality, college-level MCQ quizzes (50 comprehensive questions total) using the globally-registered Quiz component (<Quiz />). The component automatically:
Displays 15-20 random questions per session (shuffled from the 50 total)
Shows immediate feedback after each answer (correct option + explanation + why wrong if incorrect)
Shuffles questions differently on each retake (randomized batching from the same 50)
Provides progress tracking, color-coded feedback, and detailed review page
NO passing/failing threshold—just tracks score and learning
Output is ALWAYS a Quiz component with 50 questions, NEVER static markdown quizzes.
Core Principles:
Test understanding and application, not memorization
Immediate feedback per question enables real-time learning (not delayed until results page)
Randomized batching (15-20 per session) keeps students engaged across multiple attempts
Provide meaningful explanations addressing all misconceptions
No pass/fail threshold—focus on learning, not grading
When to Activate
This skill should be used when creating end-of-chapter assessments. CRITICAL: This skill ALWAYS generates interactive quizzes using the Quiz component—NEVER static markdown quizzes. ALWAYS 50 QUESTIONS TOTAL.
Activate this skill when:
Creating end-of-chapter assessments that MUST use the Quiz component
Need college-level conceptual questions (50 comprehensive questions total)
Want interactive quiz with immediate feedback per question (not delayed until results)
Want randomized batch display (15-20 questions per session, different batches on retake)
Want instant explanations showing correct option AND why wrong answers are incorrect
Need fully responsive, accessible quiz with light/dark theme support
Creating MDX-compatible quiz files using <Quiz /> component
Trigger phrases:
"Create a quiz for Chapter X"
"Generate a 50-question quiz for Chapter X"
"Build an interactive quiz with immediate feedback"
"Create chapter assessment with randomized batching"
"Generate college-level assessment with 50 questions"
MANDATORY REQUIREMENTS:
Use Quiz component (NEVER static markdown)
Generate 50 total questions (comprehensive chapter coverage)
Component displays 15-20 per batch (randomized each retake)
Randomize correctOption indices evenly across 0-3
Explanations MUST address why wrong answers are incorrect
NO passing score threshold—just score tracking
Immediate feedback shown after each answer
🚨 CRITICAL: ALL options within ±3 words of each other per question (prevents test-takers from guessing by selecting longest/shortest option)
🚨 MANDATORY VALIDATION: Manually count words for EVERY option in EVERY question (all 50 questions) before submitting quiz
🚨 CRITICAL: Verify correct answer is NOT correlated with option length (longest option must NOT be more frequently correct)
Key Concepts
College-Level Conceptual Questions
Shift from Recall to Understanding:
❌ Recall (Avoid):
"What is a Python list?" → Tests memorization
✅ Conceptual (Target):
"Given this code with list operations, what misconception does this error reveal?" → Tests understanding
Why College-Level?
Job readiness: Professional developers need to understand WHY, not just WHAT
AI-era skills: With AI generating code, understanding concepts matters more than syntax recall
Transfer learning: Conceptual knowledge transfers; memorized facts don't
Misconception correction: Explain WHY their wrong answer was incorrect right away
Better explanations: Space for 100-200 word explanations per question (comprehensive, not rushed)
Feedback shows:
✅ Correct answer highlight (green background on correct option)
✅ Why your answer was wrong (if incorrect: "You selected X, but this is incorrect because...")
✅ Correct option named (The correct answer is: Y)
✅ Full explanation (80-150 words explaining concept, addressing misconceptions, real-world connection)
Example feedback structure:
✓ CORRECT!
[Explanation of why this is right...]
vs.
✗ INCORRECT
Why your answer was wrong:
You selected: "append() is immutable"
This is incorrect. The correct answer is: "append() modifies the list in place"
Explanation:
Lists are mutable (changeable) in Python. The append() method modifies the original list
in place and returns None (doesn't return a new list). This is different from strings,
which are immutable. Understanding mutability is crucial for debugging...
50-Question Bank with Randomized Batching
Why 50 questions?
Comprehensive coverage: 50 questions ensure all chapter concepts are thoroughly tested
Spaced repetition: Student can take quiz multiple times, seeing different questions each time
You provide all 50 questions to the Quiz component
Component shuffles all 50 on mount
Component displays questions 1-15 (or 1-20) for user to answer
User completes batch, sees results page
User clicks "Try Another Batch" → Component reshuffles all 50
Component displays a NEW random batch of 15-20 (completely different questions)
Example flow:
Session 1: User sees questions [3, 47, 12, 28, 5, 11, ...] (15-20 questions)
Completes, sees results: 14/18 correct
User clicks "Try Another Batch" →
Session 2: User sees questions [42, 8, 31, 1, 19, 35, ...] (15-20 DIFFERENT questions)
Takes quiz again: 16/19 correct
Session 3: User clicks "Try Another Batch" →
Component shows completely DIFFERENT shuffle: [25, 9, 48, 2, 18, ...]
Option Length Validation (CRITICAL - Test Validity)
THE PROBLEM: Options of unequal length allow test-takers to guess correctly without reading questions. Example:
❌ "Yes" (2 words) vs. "Organizational capabilities create guardrails preventing failures" (6 words) → Students select longest without reading
❌ Longest option is correct 80% of the time → Test measures reading strategy, not understanding
THE SOLUTION:ALL options within ±3 words of each other across all 50 questions.
Validation Procedure (MANDATORY):
Count words for EVERY option in EVERY question (all 50 questions):
Question: "Why is X important?"
A: "It improves performance quickly" (4 words)
B: "It simplifies code structure" (4 words)
C: "It prevents common bugs" (4 words)
D: "It helps developers work together" (5 words) ✓ All within ±3 range (4-5 is acceptable)
Flag any question failing the ±3 word rule:
❌ FAIL:
A: "Yes" (2 words)
B: "The framework processes requests asynchronously in a single event loop without blocking" (12 words)
→ Difference: 10 words → FAIL (>3 word difference)
✅ PASS:
A: "AI amplifies existing practices" (4 words)
B: "AI fixes all problems" (4 words)
C: "AI changes developer roles" (4 words)
D: "AI prevents errors completely" (4 words)
→ All within 4-4 range → PASS
Verify length distribution (no correlation with correctness):
Count how many correct answers are in longest option group
Count how many correct answers are in shortest option group
Should be roughly equal (not "longest is always correct")
Document validation in handoff:
Option Length Validation Complete:
✓ All 50 questions checked
✓ All options within ±3 word range
✓ No length-correctness correlation
✓ Longest option correct in 6 questions
✓ Shortest option correct in 7 questions
✓ Middle-length correct in 12 questions
Why ±3 words matters:
4-5 words: Similar cognitive load, hard to distinguish by scanning
10+ word difference: Readers start pattern-matching (always pick longest/shortest)
±3 rule: Prevents strategic test-taking without reading
Correct answers distributed across 0-3 indices (not a/b/c/d)
For 50 questions: ~12-13 per index (25% each)
No obvious patterns
Maximum 2 consecutive same answers
Quiz Component Format:
{
question: "Your question?",
options: ["Option A", "Option B", "Option C", "Option D"],
correctOption: 2, // Index 0-3, NOT 1-4!explanation: "Why this is correct AND why other options are wrong..."
}
Workflow: Generate → Redistribute → Validate
LLMs are excellent at content creation but struggle with strict procedural constraints like answer distribution. Therefore, this skill uses a two-step process:
Step 1: Generate Quiz (Content Creation)
Write all 50 questions first (focus on quality, don't worry about correctOption distribution)
Use natural answer placement (what makes pedagogical sense)
explanation: "Lists are mutable (changeable) in Python, so append() modifies the original
list in place. This is different from strings, which are immutable—you can't change them
after creation. The extend() method adds multiple items (like appending a list), but
append() adds a single item. Insert() requires both value and position. Understanding
mutability is crucial for debugging variable scope issues and understanding function
side effects. When a function calls append() on a list parameter, it modifies the
original list outside the function—a common source of bugs."
Source Field (Lesson Attribution)
The source field links each question to the specific lesson it addresses. This helps students know which lesson material to review.
Format:"Lesson N: [Lesson Title]"
Source Extraction:
Extract lesson number from lesson file name (01, 02, 03, etc.)
Extract lesson title from lesson .md file's title metadata (the title: field in YAML frontmatter)
Quiz is already chapter-specific, so chapter info is redundant
Examples:
source: "Lesson 1: Understanding Mutability"source: "Lesson 3: Scope and Closures"source: "Lesson 2: Unit Test Design"
Helps students quickly navigate to the relevant lesson if they want to review
Quiz Architecture
Fixed Constraints (Non-Negotiable)
question_count:50# Comprehensive bank (50 total questions)questions_per_batch:15-20# Questions displayed per session (component shuffles)options_per_question:4# Always exactly 4 optionsquestion_format:multiple_choice# Only MCQcorrect_answer_distribution:random_equal# indices 0-3 equally distributed (~12-13 per index)feedback_timing:immediate# Shown after each answer (not delayed)passing_score:NONE# No pass/fail threshold—just score trackingfile_naming:##_chapter_##_quiz.md # e.g., 05_chapter_02_quiz.mdoutput_format:MarkdownwithQuizcomponent# <Quiz {...} questions={[...50 questions...]} />component_globally_registered:true# No imports needed
CRITICAL ANTI-PATTERNS:
❌ Fewer than 50 questions (comprehensive coverage requires full 50)
Use Read tool to access references as needed during quiz generation.
**Quiz Generator v4.0.0 ALWAYS creates interactive assessments using the globally-registered Quiz component with 50 COMPREHENSIVE QUESTIONS. NEVER creates static markdown quizzes or fewer than 50 questions. Component automatically displays 15-20 random questions per batch, shuffled differently on each retake. Features immediate feedback per question (correct option + explanation + why wrong if incorrect), no passing/failing threshold (just score tracking), progress tracking, answer validation, color-coded feedback, retake button, and full theme support.
Every quiz MUST:
Use component with 50 questions
Have randomized correctOption indices (0-3) evenly distributed
Include 100-150 word explanations addressing all 4 options
Include source field for all questions (format: "Lesson N: [Lesson Title]")
ENFORCE STRICT OPTION LENGTH VALIDATION: ALL options within ±3 words of each other for ALL 50 questions (manually verified, not assumed)
VERIFY no correlation between option length and correctness (longest option NOT biased toward being correct)
