Skill: ivangdavila/quiz (version 1.0.0)

--- name: Quiz description: Design engaging quizzes with effective questions, scoring logic, and results that drive learning or conversions. --- ## Situation Detection | Context | Load | |---------|------| | Knowledge assessment, exams, certifications | `types.md` → Knowledge section | | Personality quizzes, "Which X are you?" | `types.md` → Personality section | | Lead generation, marketing quizzes | `types.md` → Lead-gen section | | Writing effective questions | `questions.md` | | Building quiz UI/UX, gamification | `implementation.md` | --- ## Universal Rules **One concept per question.** Double-barreled questions confuse and measure nothing. "Do you like pizza and exercise?" → Bad. **Wrong answers must be plausible.** If correct answer is obvious by elimination, you're testing pattern recognition, not knowledge. **Results must feel personal.** Generic outcomes kill engagement. "You got 7/10" loses to "You're an 80s Movie Expert — you caught references most people miss." **Progress visibility motivates.** Show question count, progress bar, time remaining. Uncertainty creates anxiety and abandonment. --- ## Quiz Types Quick Reference | Type | Goal | Typical Length | Results | |------|------|----------------|---------| | Knowledge | Assess learning | 10-20 questions | Score + feedback per answer | | Personality | Engagement, sharing | 5-12 questions | Personality type/category | | Assessment | Diagnose level/fit | 10-30 questions | Detailed report | | Lead-gen | Capture email | 5-8 questions | Results gated behind email | | Trivia | Entertainment | Any | Leaderboard, social share | --- ## Question Design Checklist - [ ] Clear, unambiguous wording - [ ] One correct answer (or explicit multi-select instruction) - [ ] Distractors are plausible, not obviously wrong - [ ] No "all of the above" or "none of the above" (lazy design) - [ ] Avoid negatives ("Which is NOT...") - [ ] Test the concept, not reading comprehension --- ## Scoring Patterns **Simple percentage:** Correct/total × 100. Best for knowledge tests. **Weighted scoring:** Some questions worth more. Good for prioritized competencies. **Branching outcomes:** Answer combinations map to results. Used in personality quizzes. **Diagnostic rubric:** Score across multiple dimensions. Best for assessments and skill evaluations. --- ## Engagement Boosters - Immediate feedback after each answer (right/wrong + explanation) - Visual progress indicator - Streak rewards ("3 in a row!") - Time pressure (optional, increases excitement but also anxiety) - Social sharing of results - Leaderboards for competitive contexts --- ## Red Flags - All correct answers in position B/C → Detectable pattern - Questions testing obscure trivia vs actual learning objectives - Results that don't connect to actions ("Now what?") - Too long with no progress indication → Abandonment - Mobile-unfriendly UI (tiny buttons, horizontal scroll) --- ## When to Load More | Situation | Reference | |-----------|-----------| | Designing for specific quiz type | `types.md` | | Writing and reviewing questions | `questions.md` | | Building quiz flow, UI, tools | `implementation.md` |

path: implementation.md
content: # Quiz Implementation

## Platforms and Tools

### No-Code Quiz Builders
- **Typeform:** Beautiful UX, good for lead-gen and personality quizzes
- **Interact:** Specifically designed for marketing quizzes
- **Google Forms:** Free, basic, good for internal assessments
- **JotForm:** Flexible, many templates
- **Quizlet:** Best for flashcard-style learning

### LMS-Integrated
- **Canvas, Moodle, Blackboard:** Built-in quiz tools for courses
- **Articulate/Storyline:** E-learning with advanced branching
- **LearnDash (WordPress):** Course quizzes with gamification

### Custom Development
Build your own when:
- Need specific scoring logic
- Adaptive/branching complexity
- Integration with existing systems
- Custom gamification features
- Data ownership requirements

---

## Data Model

Basic quiz structure:

```
Quiz
├── id, title, description, settings
├── Questions[]
│   ├── id, text, type, order
│   ├── Options[]
│   │   ├── id, text, isCorrect, points
│   │   └── outcomeMapping (for personality)
│   └── explanation (for feedback)
├── Outcomes[] (for personality/assessment)
│   ├── id, title, description, imageUrl
│   └── minScore/maxScore or trait mapping
└── Results[]
    ├── id, quizId, userId, timestamp
    ├── answers[], score, duration
    └── outcomeId (if applicable)
```

---

## UX Patterns

### Progress Indication
- Progress bar (current question / total)
- Question numbers: "3 of 10"
- Percentage complete
- Estimated time remaining

### Navigation
- Linear (forced order) vs. Free (jump around)
- Allow review before submit (or not, for timed exams)
- Mark questions for review

### Feedback Timing
- **Immediate:** After each question (best for learning)
- **End of quiz:** All feedback at once (better for assessment purity)
- **Delayed:** After deadline (for exams/certifications)

### Mobile Optimization
- Large tap targets (44px minimum)
- Readable text without zoom
- Vertical scrolling only
- No hover-dependent interactions
- Progress saves on connection loss

---

## Gamification Elements

| Element | Purpose | When to Use |
|---------|---------|-------------|
| Points | Quantify achievement | Knowledge, trivia |
| Badges | Mark milestones | Repeated engagement |
| Leaderboards | Competition | Trivia, community quizzes |
| Streaks | Habit formation | Daily/regular quizzes |
| Timers | Pressure/excitement | Trivia, challenges |
| Lives | Stakes | Competitive modes |
| XP/Levels | Long-term progression | Learning platforms |

**Warning:** Gamification can backfire. Timer anxiety, leaderboard discouragement, badge inflation. Use thoughtfully.

---

## Scoring Implementation

### Simple Scoring
```
score = correct_answers / total_questions * 100
```

### Weighted Scoring
```
score = sum(question.points for correct answers) / max_possible
```

### Personality/Outcome Scoring
```
for each answer:
  outcome_scores[answer.mapped_outcome] += 1
result = outcome with highest score
```

### Diagnostic Rubric
```
for each competency:
  competency_score = sum(points for relevant questions) / max
results = {competency: score, ...}
```

---

## Analytics to Track

**Quiz-level:**
- Completion rate (started vs finished)
- Average score
- Time to complete
- Drop-off points (which question causes abandonment)

**Question-level:**
- % correct
- Average time per question
- Distractor analysis (which wrong answers chosen)
- Skip rate (if allowed)

**User-level:**
- Score distribution
- Retake behavior
- Progress over time
- Correlation with outcomes (did learning improve?)

---

## Anti-Cheating Considerations

**For low-stakes:** Not worth the friction. Accept some cheating.

**For medium-stakes:**
- Randomize question order
- Randomize option order
- Question pools (different questions per attempt)
- Time limits
- No back-navigation

**For high-stakes:**
- Proctoring (human or AI)
- Browser lockdown
- Identity verification
- Plagiarism detection
- Multiple versions of exam


path: questions.md
content: # Writing Effective Quiz Questions

## Question Structure

**Stem:** The question or incomplete statement.
- Clear and concise
- Contains all necessary context
- One interpretation only
- Avoid negatives ("Which is NOT...")

**Correct answer:** Obviously correct to someone who knows the material.

**Distractors:** Wrong answers that seem plausible to someone who doesn't know.

---

## Good Distractors

Distractors should be:
- Grammatically consistent with stem
- Similar length to correct answer
- Plausible (common misconceptions, related concepts)
- Not obviously wrong

**Bad distractors:**
- Joke answers
- "All of the above" / "None of the above"
- Answers that don't grammatically fit the stem
- One obviously wrong with three plausible options

**Good distractor sources:**
- Common mistakes students make
- Related but incorrect concepts
- Partial truths
- Things that sound right but aren't

---

## Question Types

### Multiple Choice
Best for: Knowledge verification, recognition.

```
What is the capital of Australia?
A) Sydney ← Common misconception
B) Melbourne ← Second-largest city
C) Canberra ← Correct
D) Brisbane ← Another major city
```

### True/False
Best for: Binary facts, quick checks.
- Avoid double negatives
- Statement should be clearly true OR false
- Don't use "always" or "never" (usually make answer obvious)

### Fill in the Blank
Best for: Recall, terminology.
- Blank should be a key concept, not trivial word
- Only one correct answer (or explicit list of acceptable alternatives)
- Provide context around the blank

### Matching
Best for: Relationships, categories, definitions.
- More options than stems (prevents elimination guessing)
- Clear relationship being tested
- All items in same category

### Ordering/Sequencing
Best for: Processes, timelines, procedures.
- Steps should be distinct (not interchangeable)
- 4-7 items (more becomes tedious)

---

## Difficulty Calibration

**Easy:** Tests recognition of key concepts.
- Direct recall from material
- Obvious distractors
- Single-step thinking

**Medium:** Tests understanding and application.
- Requires connecting concepts
- Plausible distractors from related topics
- May require 2-step reasoning

**Hard:** Tests analysis, synthesis, edge cases.
- Subtle distinctions
- All options seem plausible
- Requires deep understanding or experience

**Calibration process:**
1. Write questions targeting each difficulty level
2. Test with 5-10 people
3. If >90% get it right → Too easy
4. If <30% get it right → Too hard or unclear
5. Adjust based on actual performance data

---

## Common Mistakes

**Double-barreled questions:**
❌ "Do you understand variables and loops?"
✅ Split into two questions

**Testing trivia vs objectives:**
❌ "In what year was Python created?"
✅ "What does the `len()` function return?"

**Clues in the question:**
❌ "What is the largest mammal in the ocean?"
(ocean = hint toward whale)
✅ "What is the largest mammal on Earth?"

**Correct answer longer than distractors:**
People tend to pick the most detailed answer. Make all options similar length.

**Pattern in answer positions:**
Randomize correct answer positions across quiz.

---

## Review Checklist

Before publishing questions:
- [ ] Stem is clear and unambiguous
- [ ] Only one defensibly correct answer
- [ ] Distractors are plausible
- [ ] No grammatical clues
- [ ] Appropriate difficulty for audience
- [ ] Tests actual learning objective
- [ ] Explanation ready for incorrect answers


path: types.md
content: # Quiz Types

## Knowledge Quizzes

**Purpose:** Assess learning, certify competency, reinforce material.

**Best practices:**
- Align questions to learning objectives (if no objective, question doesn't belong)
- Mix difficulty levels (easy → medium → hard builds confidence)
- Provide immediate feedback with explanations
- Allow review of incorrect answers after completion
- Consider retakes with question shuffling

**Question formats:**
- Multiple choice (4-5 options ideal)
- True/False (use sparingly — 50% guess rate)
- Fill in the blank (tests recall, not recognition)
- Matching (good for relationships and categories)
- Ordering/sequencing (for processes)

**Scoring:** Percentage or points. Consider partial credit for multi-part questions.

---

## Personality Quizzes

**Purpose:** Entertainment, engagement, self-discovery, shareability.

**Best practices:**
- 5-12 questions max (attention span)
- Questions should feel revealing but fun
- Every answer maps to one or more outcome traits
- Results must feel personalized and positive
- Include shareable image with result

**Question formats:**
- "Which would you rather..." scenarios
- Image selection ("Pick the room you'd live in")
- Sliding scales ("Introvert ← → Extrovert")
- Forced ranking

**Scoring:** Each answer adds points to outcome categories. Highest score determines result.

**Outcomes:** 4-8 result types. Each needs:
- Catchy name ("The Strategist", "The Creative")
- Detailed description (why this fits them)
- What it means for them
- Call to action or recommendation

---

## Assessment Quizzes

**Purpose:** Diagnose skill level, identify gaps, recommend next steps.

**Best practices:**
- Test across multiple competency areas
- Adaptive difficulty if possible (harder questions after correct answers)
- Results show strengths AND growth areas
- Actionable: "Based on your results, we recommend..."
- Often used for course placement, hiring, or training needs analysis

**Question formats:**
- Scenario-based ("What would you do if...")
- Case studies with multiple questions
- Practical application problems
- Self-assessment scales (with behavioral anchors)

**Scoring:** Multi-dimensional rubric. Score each competency area separately.

**Results:** Spider/radar chart showing competency levels. Narrative explanation. Recommended actions.

---

## Lead Generation Quizzes

**Purpose:** Capture email addresses by gating valuable results.

**Best practices:**
- Value of results must exceed friction of email entry
- 5-8 questions max (fast completion)
- Show progress: "Almost there!"
- Gate AFTER completion, BEFORE results
- Results page = landing page (CTA, offer, next step)

**Effective topics:**
- "What type of X are you?" (curiosity)
- "How ready are you for Y?" (self-assessment)
- "Which Z is right for you?" (product recommendation)
- "Test your knowledge of..." (ego challenge)

**Email capture best practices:**
- Explain what they'll get (detailed results, PDF, etc.)
- Minimal fields (email only, or email + first name)
- Privacy reassurance
- Mobile-optimized form

---

## Trivia Quizzes

**Purpose:** Entertainment, community engagement, brand awareness.

**Best practices:**
- Mix easy and hard (everyone should get some right)
- Interesting facts in answer explanations
- Timer adds excitement (optional)
- Leaderboards drive competition
- Regular new quizzes keep users returning

**Formats:**
- Daily/weekly quizzes
- Themed rounds
- Multiplayer real-time
- Progressive difficulty

**Gamification:**
- Points and streaks
- Badges and achievements
- Social sharing ("I scored 8/10 on...")
- Head-to-head challenges


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)