Skip to content

aiskillstore/marketplace / skills/92bilal26/quiz-generator

quiz-generator

Verified

Generate 50-question interactive quizzes using the Quiz component with randomized batching. Use when creating end-of-chapter assessments. Displays 15-20 questions per session with immediate feedback. NOT for static markdown quizzes.

references/generation-process.md

View on GitHub
# Quiz Generation Process - 7 Stages (v4.0.0)

This document details the complete 7-stage process for generating 50-question college-level quizzes using the globally-registered Quiz component with immediate feedback and randomized batching.

---

## Process Overview

```
Chapter Content (docs/) + Lessons
    ↓
1. Analyze Chapter Structure (all concepts)
2. Generate 50 Conceptual Questions
3. Design Meaningful Distractors
4. Randomize Correct Answers (indices 0-3, ~12-13 per index)
5. Write Comprehensive Explanations (100-150 words each)
6. Format Quiz Component (with all 50 questions)
7. Validate Distribution & Format
    ↓
##_chapter_##_quiz.md (with <Quiz /> component displaying 15-20/batch)
```

---

## Stage 1: Analyze Chapter Structure

**Goal:** Understand chapter scope, identify all lessons, and map key concepts.

**Process:**

1. **Read chapter content:**
   - Examine docs/[chapter-path]/ directory
   - List all lesson files (lesson-1.md, lesson-2.md, etc.)

2. **Identify lessons:**
   - Note key concepts taught in each lesson
   - Identify prerequisite chapters referenced
   - Map which concepts are foundational vs. advanced

3. **Extract learning objectives:**
   - What can students do after this chapter?
   - What concepts are foundational vs. advanced?
   - What common mistakes are mentioned?

**Artifacts:**
- Chapter outline with all lessons
- Comprehensive concept map (all topics across all lessons)
- Learning objectives list (for ALL lessons)
- Common mistakes inventory (across entire chapter)

---

## Stage 2: Generate 50 Conceptual Questions

**Goal:** Write 50 understanding-focused questions covering ALL chapter material comprehensively.

**Strategy:**

For a chapter with N lessons, generate 50 questions targeting:
- **All major concepts:** Every significant topic gets multiple questions (3-5 per major topic)
- **Foundational concepts:** Topics that unlock understanding of other topics
- **Complex topics:** Concepts students struggle with most (higher question density)
- **Application scenarios:** Real-world usage demonstrating mastery (throughout)
- **Misconception-prone areas:** Topics with documented common errors

**Why 50 Questions?**

The Quiz component with 50-question bank enables:
- **Comprehensive coverage:** Every concept thoroughly tested, not just highlights
- **Spaced repetition:** Students see different questions each retake (new batch each time)
- **Long-term retention:** 50 unique questions → better recall than 15-20 repeated questions
- **Flexible batching:** Component displays 15-20 per session, shuffled differently on retake
- **Pedagogical soundness:** Aligns with spaced repetition and interleaving research

**Cognitive Level Distribution (College Standard):**

Target across all 50:
- **Remember:** 2-3 questions (4-6%) - Minimal recall
- **Understand:** 8-10 questions (16-20%) - Concept grasp
- **Apply:** 20-25 questions (40-50%) - Use in context ← PRIMARY TARGET
- **Analyze:** 12-15 questions (24-30%) - Debug, compare, diagnose ← SECONDARY TARGET
- **Evaluate:** 3-4 questions (6-8%) - Judge quality, tradeoffs

**Requirement:** 75%+ questions at Apply level or higher (college standard, ~40+ of 50 questions)

---

## Stage 3: Design Meaningful Distractors with Equal-Length Options

**Goal:** Create 3 plausible wrong answers that diagnose specific misconceptions (3 distractors per question × 50 = 150 total distractors), all with equal length to prevent length-based guessing.

**Question Quality Criteria:**

✅ **Good Conceptual Questions (testing understanding):**
- Require understanding WHY, not just WHAT
- Present realistic code scenarios or debugging situations
- Test debugging, prediction, or analysis skills
- Ask about tradeoffs, design decisions, or best practices
- Require analysis of behavior or consequences
- Connect multiple concepts from the chapter

❌ **Poor Recall Questions (avoid entirely):**
- "What is a Python list?" (definition, memorization)
- "Which file stores configuration?" (memorization)
- "What is OAuth?" (terminology)
- "List three CLI commands" (pure recall)

**Distractor Design:**

For each of the 50 questions, create 3 meaningful distractors testing specific misconceptions:
1. **Common student error 1:** Most frequent misunderstanding about this concept
2. **Common student error 2:** Second misconception based on partial understanding
3. **Common student error 3:** Related misconception or opposite logic

**CRITICAL: Equal-Length Options (Anti-Cheating Measure)**

**ALL 4 options MUST be within ±3 words of each other.** This prevents length-based guessing:
- ❌ DON'T: Option A (5 words) vs. Option B (18 words) → Student guesses longest
- ✅ DO: All options 10-13 words → Length doesn't reveal correct answer
- ✅ DO: All options 8-11 words → Student must read carefully, not guess by length

**Word Count Process:**
1. After writing all 4 options, count words in each
2. Verify all options are within ±3 words (e.g., 10, 11, 13, 12 words = ✅ PASS)
3. If out of range, reword option(s) to match length
4. **CRITICAL: Don't make the correct option longest/shortest to compensate**
5. Randomize correctOption indices across 0-3 (correct answer should NOT correlate with length)

**Example (EQUAL LENGTH):**
```
Question: "What happens when you modify a list passed to a function?"
A) "A copy is created, original stays unchanged" (8 words)
B) "The original list is modified in place" (7 words) ← CORRECT
C) "Only the function's copy gets modified" (6 words)
D) "Lists cannot be passed to functions at all" (8 words)

Word counts: 8, 7, 6, 8 → Within ±3 words ✅
Correct is in position 1 (not longest, not shortest) ✅
```

**Example (WRONG - Length-Based Guessing):**
```
❌ BAD:
A) "A copy is made" (4 words)
B) "The original list object is modified because Python passes mutable objects by reference, affecting the shared state" (17 words) ← CORRECT
C) "Copy" (1 word)
D) "Changed" (1 word)

Problem: Option B obviously longest → students guess it and score 90%+ without understanding
```

---

## Stage 4: Randomize Correct Answers (Indices 0-3)

**Goal:** Eliminate answer patterns and prevent test-taking shortcuts.

**Requirements:**

- **No patterns:** Correct answer must appear randomly (not 0,1,2,3,0,1,2,3...)
- **Equal distribution:** Each index (0/1/2/3) correct roughly equal times
- **No runs:** Avoid 3+ consecutive same answer indices
- **True randomness:** Shuffle correctOption values after writing questions (then verify distribution)

**Distribution Targets for 50 Questions:**

```
Index 0 correct: 12-13 times (24-26%)
Index 1 correct: 12-13 times (24-26%)
Index 2 correct: 12-13 times (24-26%)
Index 3 correct: 12-13 times (24-26%)
Max consecutive same: 2
Total: 50 questions = 100%
```

**Ideal distributions:**
- ✅ 0(13) 1(13) 2(12) 3(12) = 50 total (perfect)
- ✅ 0(12) 1(13) 2(12) 3(13) = 50 total (acceptable)
- ✅ 0(13) 1(12) 2(13) 3(12) = 50 total (perfect)

**Avoid:**
- ❌ 0(20) 1(10) 2(10) 3(10) = 50 total (uneven)
- ❌ 0(25) 1(15) 2(5) 3(5) = 50 total (very uneven)

**How to Randomize:**
1. Write all 50 questions with focus on content (don't worry about correctOption position)
2. After writing ALL 50, identify which position should be correct for each
3. Shuffle the answer indices randomly (move correct answer to 0/1/2/3)
4. Count each index across all 50 questions → verify ~12-13 per index
5. Ensure no 3+ consecutive same correctOption values
6. Document the randomization in the questions array

See [answer-distribution.md](./answer-distribution.md) for verification methods.

---

## Stage 5: Write Comprehensive Explanations (100-150 words)

**Goal:** Provide rich learning through detailed explanations shown immediately after each answer.

**Explanation Requirements (CRITICAL for immediate feedback model):**

Every explanation (for all 50 questions) MUST:
1. **Explain WHY it's correct** - 2-3 sentences explaining the concept deeply
2. **Address why EACH of the 3 distractors is wrong** - 1-2 sentences per distractor explaining the specific misconception
3. **Provide additional context** - Real-world connection, misconception clarification, or extension (1-2 sentences)
4. **Total: 100-150 words addressing all 4 options explicitly**

**Explanation Template:**

```javascript
explanation: "Option B is correct because [2-3 sentences explaining the concept and why it's right].
Why not the others? Option A [1-2 sentences explaining the misconception].
Option C [1-2 sentences explaining the misconception].
Option D [1-2 sentences explaining the misconception].
[1-2 sentences providing real-world connection or extended context about the concept]."
```

**Why Immediate Feedback is Powerful:**
- Shows explanation right after student selects an answer (before moving to next question)
- Enables instant reinforcement (learning happens in moment of mistake)
- Allows 100-150 word explanations (more space for comprehensive teaching)
- Color-coded UI: green highlight for correct option, red for incorrect selection
- "Why your answer was wrong" section shows exactly what student misunderstood

**Word Count Verification (MUST DO):**
- Target: 100-150 words per explanation
- Count: Explain correct (30-40 words) + 3 distractors (20-30 words each) + context (15-25 words)
- Verify: Each explanation must address all 4 options explicitly

---

## Stage 7: Format Quiz Component

**Goal:** Create valid markdown file with Quiz component JSX.

**File Structure:**

```markdown
---
sidebar_position: X  # e.g., 06 (lessons + 1)
title: "Chapter X: [Topic] Quiz"
---

# Chapter X: [Topic] Quiz

Brief introduction about what students should test (1-2 sentences).

<Quiz
  title="Chapter X: [Topic] Assessment"
  questions={[
    {
      question: "Question 1 text here?",
      options: [
        "Option A",
        "Option B",
        "Option C (correct)",
        "Option D"
      ],
      correctOption: 2,  // Index 0-3
      explanation: "Comprehensive explanation (60-150 words) explaining why correct,
        addressing why each distractor is wrong, and providing additional context."
    },
    {
      question: "Question 2 text?",
      options: ["Option A", "Option B", "Option C", "Option D"],
      correctOption: 0,
      explanation: "Explanation for question 2..."
    }
    // ... 6-8 more questions
  ]}
  passingScore={70}
/>
```

**Formatting Rules:**

1. **YAML Frontmatter:** sidebar_position and title (description optional)
2. **Header:** Clear chapter and topic identification
3. **Introduction:** 1-2 sentences about what to expect
4. **Quiz Component:**
   - title prop: Quiz name/description
   - questions array: Array of 5-10 question objects
   - Each question has: question, options (exactly 4), correctOption (0-3), explanation
   - passingScore prop: 60-70 (60% for beginners, 70% for intermediate)
5. **No imports needed:** Quiz component is globally registered
6. **Valid JSX syntax:** Proper JavaScript object syntax within the component

**Key Requirements:**

✅ Exactly 4 options per question
✅ correctOption uses 0-3 index (NOT 1-4!)
✅ Explanations address why each distractor is wrong
✅ No imports needed for `<Quiz />`
✅ File named: `##_chapter_##_quiz.md`

See [file-naming.md](./file-naming.md) for naming conventions.

---

## Validation Checklist

**Content Validation:**
- [ ] 5-10 questions total (focused assessment)
- [ ] All questions are conceptual (75%+ Apply or higher)
- [ ] No recall-only questions ("What is X?")
- [ ] All scenarios are realistic and relevant
- [ ] Each question tests a distinct concept

**Component Format Validation (CRITICAL):**
- [ ] Valid JSX syntax in markdown file
- [ ] Exactly 4 options per question
- [ ] correctOption uses 0-3 indices only (NOT 1-4!)
- [ ] All question objects properly formatted
- [ ] explanations address all distractors
- [ ] passingScore property set (60-70)
- [ ] No syntax errors in options array

**Answer Distribution Validation:**
- [ ] Correct answers distributed evenly across 0-3 indices
- [ ] For 8 Qs: each index correct ~2 times (25%)
- [ ] For 10 Qs: each index correct 2-3 times (20-30%)
- [ ] No patterns (e.g., 0,1,2,3,0,1,2,3...)
- [ ] No 3+ consecutive same correctOption values
- [ ] Verified manually (not assumed)

**Format Validation:**
- [ ] Valid markdown syntax
- [ ] Proper YAML frontmatter
- [ ] Quiz component properly formatted
- [ ] File named correctly: ##_chapter_##_quiz.md
- [ ] File uses `.md` extension
- [ ] Saved to correct lesson directory

See [quality-checklist.md](./quality-checklist.md) for complete validation criteria.

---

**Keywords for grep:** process, stages, workflow, generation, analyze, select, generate, design, randomize, write, format, validate, step-by-step, methodology, Quiz component
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall