pop-quiz

name	pop-quiz
description	Use when the user wants to be quizzed or tested on work that was just built for them. Triggers include "quiz me", "test my understanding", "do I actually get this", "pop quiz on what you built", "test me on this branch". Not for explaining or re-teaching the work — only when they want to be tested on it.

Pop Quiz

Overview

After an agent builds something, this skill flips the roles: the agent springs an oral exam on the user about the work — the concepts, the terms, and above all the design tradeoffs behind each decision. The user asked for it, so the surprise isn't that there's an exam — it's which decisions get probed, and how deep the "why" goes.

Core principle: You don't understand a decision until you can explain why the rejected alternatives are worse. Target the why, not the what; grade the answer, never the person. The goal is sharper calls next time, not a humbling.

When to use

When the user asks to be quizzed/tested on work just built — not when they want it explained (that's a walkthrough). For trivial/mechanical work (renames, formatting, version bumps) there's little to learn: don't pad a typo into a fake exam — say so, and offer to quiz the one judgment call, the surrounding code, or skip it.

Non-negotiables

Every run must (1) make the user reason about at least one rejected alternative, and (2) grade honestly — at least one "partial/missed" when an answer earns it. Can't name a single alternative you rejected for this work? You're quizzing on too little: widen scope before asking — never fall back to pure recall.

Workflow

1. Gather the material — silently, before you ask

Honor an explicit focus first. If the user named a topic or file, that is the scope — even if other areas are richer. If it wasn't touched this session, say so and ask whether to quiz it from the code as-is or from the actual changes.

Otherwise gather richest-first:

• A — This session (if you built it). You remember what you rejected and why; the diff only shows surviving code. Recall each decision, the options compared, the tradeoffs and risks you flagged. Fresh session or someone else's branch? No such memory — say so, skip A, build from B/C. Never fabricate "alternatives we rejected" you have no record of.
• B — Git, for scope and exact facts (memory for the why; code for the what). Find the base defensively: git merge-base HEAD main, else master, else git symbolic-ref refs/remotes/origin/HEAD; then git diff <base>..HEAD and git log <base>..HEAD --oneline. No base? Use uncommitted work (git diff HEAD, --staged). No repo? Rely on the conversation.
• C — Rationale written down: why-comments, ADRs, design docs, linked PRs/issues.

Stop at 5–8 decisions with a known why — don't read the whole branch. Spanning unrelated changes? Drop the mechanical ones and tell the user what you picked and skipped. Conversation and git both empty? Don't invent a quiz — say there's nothing to test and ask them to point you at it.

Warm-up from last time: if a lessons file (step 6) holds unresolved items more than a few days old, open with one as a spaced re-test.

2. Build the answer key — then announce

Draft (silently) one line per decision:

concept/term · the choice made · the alternatives rejected · the deciding tradeoff · what breaks if it's wrong

That line is your grading key and it writes the question. Aim for 5–8 (never fewer than 5), ordered easy → hard — a default order, not a script (step 3 adapts it). If building the key surfaces a likely bug in your own implementation, flag it before starting.

Announce the exam in one line — topics, not questions — and start. Short on time? Pick the highest-value tradeoff questions and skip the warm-ups.

Example: "📝 Pop quiz on the rate limiter — algorithm, storage, and behavior under failure. Pens down, paper out — question 1…"

3. Run the quiz — one question at a time, adapt live

• Ask ONE question, then wait. Never reveal the answer in the question; no giveaway multiple-choice. Match the user's language.
• Mix the types: mostly "why X over Y", plus at least one transfer ("same design, but now <new constraint> — what gives?") and one prediction ("predict where this breaks under <stress>"). Recall only warms up.
• Read confidence before grading: "how sure — low / medium / high?"
• Adapt difficulty (aim ~70% right):
  • Two weak answers running → step down: scaffold ("forget the tradeoff — what does this do on each request?"), rebuild a win, resume.
  • Two sharp answers running → skip the warm-ups; jump to the hardest tradeoff or a transfer.
• Stuck or done? "I don't know" / "just tell me" → answer plainly, mark it unanswered, move on. "Stop" → go straight to the scorecard. A repeated wipeout → switch from exam to guided walk-through: explain, then ask.

4. Grade each answer — honest, never about the person

• Verdict — correct / partial / missed. Don't soften a wrong answer into "sort of right" — but grade the answer ("that's not it"), never the learner ("you don't get this"). A miss is a useful find, not a failing.
• Make them generate first. If the answer's incomplete, don't hand over the rest — nudge them to reach ("you've got the what; take a shot at the why — what would the alternative have cost?"). A reveal they struggled toward sticks; one they read doesn't.
• Then reveal the why — the rejected alternatives and the deciding tradeoff. Sure and wrong? Say so plainly ("you were confident — and it's the other way round; that's the one to burn in"). Unsure and right? Tell them they know it better than they think.
• The key is a draft, not gospel. Credit a different-but-sound answer. If they dispute a grade, re-check the actual code instead of defending the key — and own it if you were wrong.

5. Scorecard — lead with the plan, not the grade

Close in this order:

• Decisions to remember — 1–3 tradeoffs to carry into future calls.
• Gaps to revisit — what to study next.
• Strengths — what's solid.

A score is optional and goes last — a snapshot ("solid on the what, shakier on failure modes"), never a grade on them. Always give the scorecard for whatever was actually answered, even a 2-question run.

6. Offer to save the lessons — ask first

Don't write anything silently. Ask: "Want me to save these takeaways so they stick?" Only on yes, append a dated, re-testable entry to an existing notes file (or LEARNINGS.md, or the working dir if there's no repo):

- [ ] 2026-06-18 · rate limiter · Q: "Why token bucket over a sliding-window-log?" · A: the log stores a timestamp per request — memory grows with traffic

Storing the question (not just the note) lets a later quiz re-test it (step 1). On no, save nothing.

Question Design

Type	Weak (avoid)	Strong (use)
Recall	"What's a token bucket?"	Warm-up only
Closed	"Did we use Redis?" (yes/no leaks it)	"Why store bucket state in Redis over in-process — and when would in-process win?"
Tradeoff	—	"We picked token bucket over a sliding-window-log. What does the log buy you, and why wasn't it worth it?"
Transfer	—	"Same limiter, now per-tenant with 10k mostly-idle tenants. Does Redis-per-bucket still hold? What gives first?"
Prediction	—	"Predict what happens under a retry storm — where does it bend, where does it break?"
Failure mode	—	"If Redis goes down, what happens — and was that an acceptable tradeoff?"

Red Flags — STOP if you catch yourself

• Listing several questions at once → ask one, then wait.
• Leaking the answer (yes/no, handing over options), or revealing the why before they've attempted it → make them reach first.
• Building the quiz off the diff alone, or falling back to recall because "no alternatives came up" → mine the conversation; widen scope until you have a real tradeoff.
• Softening a wrong answer to be nice → honest verdict, warm frame.
• Grading the person instead of the answer, or stacking blunt "missed it"s → a miss is a find; keep it safe.
• Defending your answer key against a sound answer or a caught bug → the key is a draft; re-check and own it.
• Force-marching a stuck or out-of-time user → offer a hint, the answer, or the scorecard.
• Saving a lessons file unprompted, or quizzing in the wrong language → offer first; match the conversation.