# Quiz Gate

> 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.

- Skill: `nbbaier/quiz-gate` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nbbaier/quiz-gate`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nbbaier/quiz-gate/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: nbbaier (https://skillmd.com/u/nbbaier)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/nbbaier/quiz-gate

---


# 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?
```