quiz-me git:20260814.d1987f5A

Immutable. This exact content is served forever at /api/v1/blob/ecdb824fd0f74094.

---
name: "quiz-me"
description: "Verify understanding after implementation with targeted quizzes"
license: "MIT"
compatibility: "cline, claude, opencode, amp, codex, gemini, cursor, pi"
hint: "Use after completing complex work to verify understanding"
user-invocable: true
---

# Quiz Me

## When to Use

Use this skill **after implementation** when:
- You've completed a complex feature
- Need to write a PR description
- Want to verify understanding of changes
- About to present work to team
- Ensuring you stay "in the loop" with agent work

## What It Does

The agent generates a quiz about the implementation to verify your understanding. This helps you:
- Identify gaps in your knowledge
- Prepare for code review discussions
- Write better PR descriptions
- Stay engaged with increasingly capable agents

## How to Execute

### Step 1: Scope the Quiz

Determine what to test:
- Core architectural decisions
- Key implementation details
- Edge cases and error handling
- Integration points
- Trade-offs made

### Step 2: Generate Questions

Create questions across difficulty levels:

**Level 1 - Recall** (What):
- What did we implement?
- What files were changed?
- What are the main components?

**Level 2 - Understanding** (Why):
- Why did we choose this approach?
- Why not use [alternative]?
- What problem does this solve?

**Level 3 - Application** (How):
- How would you explain this to a reviewer?
- How does this integrate with existing code?
- How would you debug an issue here?

**Level 4 - Analysis** (Implications):
- What are the trade-offs?
- What could go wrong?
- What would you change if requirements changed?

### Step 3: Conduct Quiz (One Question at a Time)

Use the `ask_user_question` tool for each quiz question. Ask **one question at a time** — present it, wait for the answer, provide feedback, then move to the next. This makes the quiz feel like a conversation, not a test.

**Flow for each question:**

1. **Ask** using `ask_user_question` with the question and options
2. **Read the answer** the user selected or typed
3. **Provide feedback**: tell them the correct answer, explain why, link to code
4. **Track correctness** mentally (or note it)
5. **Proceed** to the next question

**Guidelines for using `ask_user_question`:**
- Set `header` to a short label (max 16 chars) like `"Architecture"`, `"Trade-offs"`, `"Edge Cases"`
- Write a clear `question` with context and any hint references
- Provide 2-4 concrete `options` — concise `label` (1-5 words) with descriptive `description`
- After the user answers, give the correct answer with explanation and code references

### Step 4: Review Answers

After each question response:
- **If correct**: Confirm and reinforce with additional context
- **If incorrect**: Gently correct, explain why, point to the relevant code/commit
- **If open-ended**: Evaluate against expected key points, fill in gaps

### Step 5: Summarise Results

After all questions are answered:
- Report overall understanding level
- Highlight strong areas
- Flag areas to review with code references
- Extract PR description material

## Question Templates (Mapped to ask_user_question)

### Multiple Choice — Architectural Decision

```
// Ask one at a time
ask_user_question(questions: [{
  header: "Architecture",
  question: "Why did we use GitHub App Installation flow instead of OAuth for this integration? (Hint: check auth/github/installation.ts for the decision)",
  options: [
    {
      label: "OAuth is deprecated",
      description: "GitHub still supports OAuth, so this isn't the reason"
    },
    {
      label: "Org-level access",
      description: "Installation flow provides org-level access — OAuth Apps can't access org repos"
    },
    {
      label: "Easier to implement",
      description: "Installation flow is actually more complex to set up than basic OAuth"
    }
  ]
}])

// After answer — provide feedback:
// "Correct! OAuth Apps can't access organization repositories, which is a GitHub limitation.
// Installation tokens authenticate as the app installation, giving org-level scope.
// See: auth/github/installation.ts:42-58"
```

### Fill in the Blank (using open-ended)

```
ask_user_question(questions: [{
  header: "Implementation",
  question: "What are the token lifespans in our GitHub auth? Fill in:\n- User OAuth tokens last: ______\n- Installation tokens last: ______\n- We cache installation tokens for: ______\n(Hint: check auth/github/token-cache.ts)",
  options: [
    {
      label: "6mo / 1hr / 55min",
      description: "User OAuth=6 months, Installation tokens=1 hour, Cache TTL=55 minutes (5 min buffer)"
    },
    {
      label: "1yr / 8hr / 7hr",
      description: "Incorrect — installation tokens only last 1 hour, we need a 5-minute buffer before expiry"
    },
    {
      label: "Permanent / 24hr / 23hr",
      description: "Incorrect — GitHub installation tokens have a 1-hour expiry, not 24 hours"
    }
  ]
}])
```

### Trade-off Analysis

```
ask_user_question(questions: [{
  header: "Trade-offs",
  question: "What's the main trade-off of our token caching strategy? We cache installation tokens with a 55-minute TTL.",
  options: [
    {
      label: "Speed vs staleness",
      description: "Correct — caching avoids rate limits (5000/hr) but a token could be stale for up to 5 minutes before natural expiry"
    },
    {
      label: "Memory vs latency",
      description: "The token cache is small (Redis, key pattern github:install:{id}:token) — memory isn't the constraint here"
    },
    {
      label: "Security vs simplicity",
      description: "Tokens are encrypted in Redis — security wasn't the trade-off driver for the TTL decision"
    }
  ]
}])
```

### Edge Case Question

```
ask_user_question(questions: [{
  header: "Edge Cases",
  question: "What happens when a user uninstalls the GitHub App? How does our system respond?",
  options: [
    {
      label: "Hard delete record",
      description: "We soft delete instead to preserve audit trail and cascading session cleanup"
    },
    {
      label: "Soft delete + audit",
      description: "Correct — we soft delete the installation record and cascade to invalidate all user sessions, preserving the audit trail"
    },
    {
      label: "Nothing, tokens work",
      description: "Incorrect — when uninstalled, tokens immediately stop working. We must clean up sessions"
    }
  ]
}])
```

### Code Reading Question

```
ask_user_question(questions: [{
  header: "Code Reading",
  question: "In the token refresh logic, why do we compare the cached token's expiry against a 55-minute threshold instead of the full 60 minutes?",
  options: [
    {
      label: "5-min safety buffer",
      description: "Correct! The 5-minute buffer prevents edge-case race conditions where a token expires between the cache check and the API call"
    },
    {
      label: "Rate limit overhead",
      description: "Rate limits are 5000/hr — the buffer isn't about rate limits, it's about preventing stale token usage"
    },
    {
      label: "Clock drift compensation",
      description: "While clock drift is a real concern, the primary reason is preventing token expiry during the request window"
    }
  ]
}])
```

## Complete Quiz Interaction Flow

For a typical 4-6 question quiz, the flow looks like:

```
1. Agent: "Let me quiz you on the GitHub OAuth implementation.
   I'll ask one question at a time and give feedback after each."

2. ask_user_question → Q1 (Architecture question)
   User answers
   Agent feedback: "Correct! ... See auth/github/installation.ts:42"

3. ask_user_question → Q2 (Implementation question)
   User answers
   Agent feedback: "Almost — the cache TTL is 55 minutes, not 50..."

4. ask_user_question → Q3 (Edge case question)
   User answers
   Agent feedback: "Right!..."

5. ask_user_question → Q4 (Trade-off question)
   User answers
   Agent feedback: "Good analysis..."

6. Agent: "Here's your summary:
   - Strong on architecture decisions
   - Review token caching details (auth/github/token-cache.ts)
   - PR description material from Q1 and Q4..."
```

## Best Practices

1. **One question per call**: Always use `ask_user_question` with a single-question array. Never batch questions.
2. **Give feedback immediately**: After each answer, confirm or correct with code references.
3. **Match complexity**: Quiz difficulty should match implementation complexity.
4. **Test reasoning**: Don't just ask "what", ask "why" and "how".
5. **Include context**: Reference specific code/commits for verification.
6. **Provide hints**: Include hints in the question text (not as tool hints, just inline).
7. **Wrong-answer options are educational**: Each incorrect option's description should explain why it's wrong.
8. **Limit to 4-7 questions**: Too many exhausts. Quality over quantity.

## Integration with Other Skills

- **After Implementation**: Always follow complex work with quiz
- **Before PR**: Use quiz results to write description
- **With Implementation Log**: Quiz questions based on logged decisions
- **For Documentation**: Questions reveal what needs better docs

## Success Criteria

A good quiz:
- Tests understanding at multiple levels (recall → analysis)
- Uses `ask_user_question` for focused, one-at-a-time questioning
- Provides immediate feedback with code references after each answer
- Reveals gaps in knowledge
- Helps you articulate decisions
- Prepares you for code review
- Takes 5-15 minutes to complete
- Results in better PR description
- Identifies documentation needs

## Common Pitfalls

- **Too easy**: Only testing recall ("what did we do?")
- **Too hard**: Testing minutiae not worth remembering
- **No feedback**: User doesn't learn from wrong answers
- **No context**: Questions without code references
- **Too long**: Exhausting instead of enlightening
- **Batching questions**: Asking multiple questions at once defeats the one-at-a-time flow

## Output Format

### Summary After Quiz

```markdown
# Quiz Results: [Feature Name]

## Strong Areas
- [Area 1]: Solid understanding of X
- [Area 2]: Clear grasp of Y

## Areas to Review
- [Area 1]: Unclear on Z, review [file.ts:123]
- [Area 2]: Missing context on W, see [commit abc123]

## Recommended Actions
- [ ] Review [specific code section]
- [ ] Read [specific documentation]
- [ ] Discuss [specific decision] with team

## PR Description Material
Based on your answers, include in PR:
- [Key point 1 from quiz]
- [Key point 2 from quiz]
- [Trade-off explanation from Qx]
```

The quiz becomes your PR description outline.