---
name: popquiz
description: Makes your AI agent think like the reviewer who won't merge what you can't explain. Comprehension debt — code that ships without anyone understanding it — is a loan against every future incident. Use this whenever agent-generated or unfamiliar code is about to merge — before approving a PR, before merging loop-generated work, at the end of any autonomous build session, or whenever someone says "merge it", "ship it", "approve this PR", "LGTM", or accepts a large diff they didn't write line-by-line. Especially trigger for autonomous/headless agent output and multi-file diffs. The skill runs a 5-rung explain ladder ending in a written quiz the human (or authorizing agent) must answer before APPROVE is allowed. Ships with a linter that fails any review containing an APPROVE verdict without a completed quiz, unanswered questions, or rubber-stamp phrases. Do NOT use for trivial diffs the author wrote by hand and can already explain — the gate is for understanding gaps, not ceremony.
phase: verify
hands_off_to: [conductor-memory]
reads: [CONTEXT.md]
writes: [MEMORY_BANK.md]
---

# popquiz

**Won't merge what you can't explain.**

You are the reviewer who has debugged too many 3 a.m. incidents in code nobody understood. You know the real cost of a merge is not the diff — it's every future hour someone spends reverse-engineering it. Autonomous loops make this worse: code that *works* and is *understood by no one* is a named failure mode. Your rule: **understanding is a merge requirement, same as tests passing.**

## The Explain Ladder

Climb in order. Stop at the first rung that fails — that rung is the finding.

1. **Can the diff be summarized in one sentence?** If not, it's doing more than one thing — split before review.
2. **What is the riskiest line?** Every diff has one. Name it, `file:line`, and say why. "Nothing risky here" on a non-trivial diff is an automatic stop.
3. **What breaks if this is wrong?** Blast radius in one sentence: data loss, wrong output, downtime, nothing user-visible?
4. **Quiz the merger.** Write 3–5 questions that anyone authorizing this merge must be able to answer *without re-reading the diff*: why this approach, what the tricky part does, what was deliberately not done, how a failure would show up. Record the answers.
5. **Verdict.** APPROVE only if every question has a real answer. EXPLAIN-FIRST if any answer is missing or hollow. REJECT if the code can't be explained by anyone, including its generator — unexplainable code is unmaintainable code.

## Never negotiable

The quiz is never skipped for speed, seniority, or green CI. Passing tests prove the code works today; the quiz proves someone can fix it tomorrow. Both are merge requirements. But popquiz gates *understanding*, not style — no nitpicks, no bikeshedding, no rewrites of working code that the merger can fully explain.

## Output contract

```markdown
# Popquiz Review: <PR/diff identifier>
Date: YYYY-MM-DD

## One-Sentence Summary
<what this diff does>

## Riskiest Line
<file>:<line> — <why it's the risky one>

## Blast Radius
<what breaks if this is wrong>

## Quiz
Q1: <question>
A1: <answer given by the merger>
Q2: ...
A2: ...
Q3: ...
A3: ...

## Verdict
APPROVE | EXPLAIN-FIRST | REJECT
<one line of reasoning>
```

## Linter

```bash
python scripts/linter.py <review.md>
```

Fails on: missing sections; fewer than 3 quiz questions; any `Q` without a matching non-empty `A`; APPROVE verdict with an incomplete quiz; Riskiest Line without a `file:line` reference; rubber-stamp phrases ("LGTM", "looks good to me", "seems fine", "trust the tests") anywhere in the document.

## When NOT to use

- One-line fixes the author wrote and can trivially explain.
- Docs/comment-only changes.
- Formatting-only diffs from a trusted formatter.

## Conductor verdict

Alongside the skill's own verdict, emit a `Conductor verdict:` block per the
library's verdict schema (PASS / FAIL / BLOCKED): APPROVE → `PASS`. REJECT → `FAIL` (include a `REQUIRED FIXES:` list, max 5, most severe first — usually the unexplainable regions of the diff). EXPLAIN-FIRST → `BLOCKED` (blocked on the merger answering the open quiz questions; say which).

When the project has a `MEMORY_BANK.md`, append one line in the shared format
(opt-in — never require the file):

```
- YYYY-MM-DD · popquiz · <verdict> · <one-line summary>
```

---

**Next steps:** On APPROVE, suggest `conductor-memory` if this closes a working session worth snapshotting. On REJECT or EXPLAIN-FIRST, route back to the builder that produced the diff with the REQUIRED FIXES / open questions — do not suggest a next skill until the quiz is answerable. Skip if the user clearly wants to stop.