quiz-gate

name

quiz-gate

description

Gate merges and commits of AI-implemented work behind a comprehension quiz that the USER must pass. Use this whenever a nontrivial implementation is complete and the user is about to commit, merge, open a PR, or ship — or whenever the user says "quiz me", "gate this", "do I understand this", or asks to review AI-generated changes before accepting them. Also use proactively at the end of any substantial implementation session, even if the user doesn't ask, offer the quiz before suggesting a commit.

Quiz Gate

The rule this skill enforces: no merge you can't defend live. After Claude implements something substantial, the user must be able to explain the changes as if they wrote them — in code review, in an interview, at 2am when it breaks. This skill generates a quiz about the just-completed work, grades the user's answers honestly, and only then clears the work for commit/merge.

The quiz tests the user, not Claude. Do not answer your own questions. Do not soften grading to be agreeable — a falsely passed quiz defeats the entire purpose.

When to run

• The user explicitly invokes it ("quiz me on this", "gate check").
• An implementation session is wrapping up and a commit/merge/PR is the next step. Offer it: "Want a quiz gate before this merges?" Respect a "no" — this is a discipline the user opted into, not a hostage situation.
• Skip it for trivial changes: typo fixes, dependency bumps, config tweaks, changes under ~20 lines. A quiz on trivia is noise that erodes the habit.

Generating the quiz

Scope: everything implemented since the last passed quiz gate (or session start). If implementation-notes.md exists in the repo, read it — Deviations and Spec gaps entries are the highest-value question sources, because they're exactly the decisions the user didn't make personally.

Ask 3–6 questions. Scale with the size of the change. Every question must target something that would matter in code review or when debugging under pressure:

1. Decision questions — "Why does X use approach A instead of B?" Only ask if a real alternative existed.
2. Failure-mode questions — "What happens if [input is malformed / the DO evicts / the request retries]?"
3. Location/flow questions — "Where does [state/validation/auth] live, and what's the path from request to response?"
4. Deviation questions — "The plan said X; what did we actually do, and why?" (Pull directly from implementation-notes.md.)
5. Boundary questions — "What is this change deliberately NOT handling?"

Never ask trivia: function names, syntax, line numbers, import paths, anything greppable in five seconds. If a question can be answered without understanding, cut it.

Present the quiz as a numbered list, then stop and wait for answers. Do not include the answers, hints, or a preamble that gives answers away.

Grading

Grade each answer as pass / partial / fail with one line of justification. Be honest — theory-of-mind check: if the user gave this answer to a skeptical senior engineer, would it hold?

• Pass: correct reasoning, even if informally worded.
• Partial: right direction, missing a consequence or condition that matters.
• Fail: wrong, or "I don't know."

For every partial or fail: explain the correct answer and point at the specific file/function/lines so the user reads the actual code, not just your summary. Then offer one follow-up question on the same topic to confirm the gap closed.

Verdict

• All pass → cleared. Say so plainly and proceed to commit/merge steps if asked.
• Any partial/fail → not cleared yet. Walk the gaps, re-ask, then clear. Do not clear the gate on the promise that the user will "look at it later."
• The user can override and merge anyway — it's their repo. If they do, note it once without lecturing, e.g. "Merging with 2 open gaps — logged." If implementation-notes.md exists, append the open gaps under a ## Quiz debt section.

Example

Context: Claude implemented SSE fan-out in a Durable Object per the spec.

Quiz gate — 4 questions before this merges:

1. A client's SSE connection drops for 30s and reconnects. What does it
   see — missed events, a gap, or a reset? What mechanism decides that?
2. Why does each session get its own Durable Object instead of one DO
   with a sessions map? Name one concrete thing that breaks in the
   single-DO design.
3. Where do posts live between creation and session expiry, and what
   deletes them?
4. The plan called for Last-Event-ID replay. What shipped instead, and
   what's the v2 implication? (from implementation-notes.md, Deviations)

A good grading line for a partial:

2. Partial — you're right that a single DO serializes all sessions'
   writes, but the concrete break is SSE fan-out head-of-line blocking:
   one slow client's stream backpressures the shared DO event loop.
   See `SessionDO.broadcast()` in src/session-do.ts:88–114. Follow-up:
   what bounds memory per DO when a client stops reading?