change-quiz

Change Quiz

After a long session, the diff alone undersells what changed, because much of the behavior depends on existing code paths. Build the user's understanding, then verify it.

Workflow

1. Determine scope: the current session's changes by default, or the diff/branch/PR the user points at. If there is no discernible change set, ask what to quiz on instead of guessing (a pre-work worry with no changes yet is blindspot-pass territory, not a quiz). Read the touched code and the existing code paths it plugs into. If implementation-notes.md exists, mine its Deviations and Surprises sections first — they are pre-indexed quiz material.
2. Write one self-contained HTML file (change-report.html in the project root, in the language of the conversation; inline CSS/JS, no network). It describes the current change set only — if an existing report recorded a passed quiz, rename it change-report-<YYYY-MM-DD>.html before overwriting. The report must stay out of the change set it describes: do not commit it, and if this is a git repo, exclude it locally: n=change-report.html; p="$(git rev-parse --git-path info/exclude 2>/dev/null)" && { mkdir -p "$(dirname "$p")" && { grep -qxF "$n" "$p" || echo "$n" >> "$p"; }; } 2>/dev/null || echo "note: could not exclude $n — leaving it untracked, never staging it" (worktree-safe; if the write is blocked, tell the user to add it manually and continue). The deliverable is the file itself — never render the report or quiz as a Cursor canvas: the merge gate must live in a single shareable file that opens outside the IDE. Contents:
   • Context & intent — the problem, and the shape of the solution.
   • What changed — grouped by area, each linking file paths and explaining how the change interacts with pre-existing behavior.
   • Behavior changes & risks — what users/callers will observe differently; what could break and where to look if it does.
3. End the file with a quiz: 5-8 questions, answers hidden until clicked. Each question gets a "show answer" disclosure plus a self-check checkbox; a fixed score bar tracks N/total and turns green only when total > 0 and every box is checked — an empty quiz must never display as passed. State in the report that checkboxes are self-assessment only; the authoritative pass is the in-chat grading. Target the parts most likely to surprise:
   • behavior that depends on existing code paths, not just new code
   • edge cases and failure modes the change handles (or deliberately doesn't)
   • "what happens if X" tracing questions Avoid trivia answerable by skimming the diff (file names, line counts). A good question: "The new retry wrapper calls fetchUser() — what happens on the third failure, given the existing circuit breaker in api/client.ts?" — its answer lives in how the change interacts with a pre-existing code path, not in the diff itself.
4. Hold the bar: the rule is: merge only after a perfect score.
   • Primary path: the user answers in chat before opening the hidden answers; grade strictly — for any miss, explain the right answer, point to the exact code, then ask one fresh question on the same topic. After two consecutive misses on the same topic, stop replacing: explain it thoroughly, mark that question "passed by coaching", and say so honestly in the verdict. Passed = every question answered correctly or explicitly marked passed-by-coaching.
   • Self-serve path: if the user self-checks against the hidden answers, that is honor-system and does not establish a graded pass — say so. If they claim a pass and want it to count, spot-check by asking them to restate the key points of two questions in chat. A question whose answer was already revealed can only go this route; a graded pass requires answering before revealing.
   • For the rest of this session, if asked to merge before a pass, remind the user the quiz is unpassed before running the merge (advisory only — never refuse an explicit instruction).
   • After a pass: offer to delete change-report.html, or mark it passed by inserting <!-- FIELD-GUIDE-QUIZ-PASSED <YYYY-MM-DD> --> as the file's first line, so the merge-gate hook stops reminding. If the change now needs explaining to reviewers, that handoff is pitch-explainer.