| name | pr-quiz |
| description | Quiz the PR author on their own branch before they request review, to prove they actually understand the change - especially code an AI wrote for them. Scopes the branch diff vs its base, reads the changed code, then asks graded questions about what changed, why, how it works, what it could break, and which edge cases it must handle. Presents all questions first, waits for the author's answers, then grades each honestly against the real code (Correct / Partial / Incorrect with the true answer and file:line), scores it, and gives a readiness verdict that names the areas to re-study before asking humans to review. Use when asked to quiz me on my PR/branch, "test my understanding before review", a self-check gate before opening a PR, or before requesting reviewers. Administered as an interactive multiple-choice quiz (clickable options) by default; pass --free-text for written answers, --questions N to set count, --save to write a scorecard. |
| argument-hint | [branch-or-base-ref] [--questions N] [--free-text] [--save] |
| allowed-tools | Bash, Read, Grep, Glob, Write, AskUserQuestion |
PR Quiz
Test whether the author genuinely understands their own branch before they ask
other people to spend time reviewing it. This is a self-check gate: the point is to
catch changes - often AI-written - that the author would not be able to explain or
defend in review. Be a fair but honest examiner, not a pushover.
$ARGUMENTS may name a base ref or branch to diff against; default is this branch
vs where it forked from the main line. Flags:
--questions N - target N questions (else scale to diff size, see below).--free-text - administer as a written numbered list instead of the default
interactive multiple-choice.--save - also write a scorecard file after grading.
Integrity rules (read first - the whole skill depends on these)
- Present every question before revealing any answer. Ask, then wait. Never
show the answer key alongside the questions.
- Do not give hints or the answer while the quiz is open. If the author asks
"what's the answer?" or "is it X?" before committing, decline warmly and tell
them to give their best answer first - guessing is part of the signal.
- Grade truthfully. Vague, hand-wavy, or "the AI did it" non-answers are
Partial or Incorrect, not Correct. Do not inflate the score to be nice; a false
pass defeats the entire purpose.
- Ground everything in code you actually read. Every question and every model
answer must trace to a real line in the diff. Cite
path:line. No trivia
("how many lines?"), no invented behavior.
- Credit real understanding. If the author explains it correctly in their own
words, mark it Correct even if worded differently than your key.
Process
1. Scope the change (silently)
2. Understand the code well enough to examine on it
Read the full diff plus enough surrounding context and related files to answer
every question you plan to ask. You cannot grade understanding you don't have.
Note the non-obvious parts: the design decisions, the risky lines, the edge cases,
the cross-file ripples, and anything that violates or upholds repo conventions
(for this repo e.g. @app/* import layering, all file ops via FileContext,
Jackson 3 / Spring Boot 4 APIs, engine typed-contract boundaries).
3. Build the question set
Scale count to the change unless --questions N is given:
small (< ~50 changed lines) 3-4, medium 5-8, large 9-12. Cap at 12.
Draw from these categories - weight toward the ones the diff actually exercises:
- Intent - what problem this solves; why it was needed now.
- Mechanism - how a specific non-trivial piece actually works ("walk me
through what
foo() does when called with X").
- Decisions & alternatives - why this approach over an obvious alternative;
what a reviewer would reasonably push back on.
- Blast radius - what else this touches or could break; what you'd retest.
- Edge cases - inputs/states the change must handle (null, empty, large,
concurrent, error paths).
- Conventions & correctness - does it follow the repo's rules; is there a
latent bug the author should be able to spot.
Prefer questions the author can only answer if they read and understood the code.
Keep a private answer key with
path:line for each - do not show it yet.
4. Administer the quiz
- Default (multiple choice): use the
AskUserQuestion tool. Per question write
3-4 options where every option is independently plausible - each distractor a
real-but-wrong reading of the code, not filler. Two hard rules so the answer
can't be spotted by shape rather than knowledge:
- Randomise the correct option's position across questions - never default
it to first. Spread it roughly evenly over the slots.
- Keep all options the same depth and length. Do not describe the correct
one more fully than the distractors - a longer or more-detailed option is a
dead giveaway. Trim the right answer or flesh out the wrong ones until a
reader can't tell them apart by size.
The tool caps a call at 4 questions, so ask in batches of 4 - but run them as
one continuous flow: fire the next batch immediately after the previous
returns, with no narration ("Round 2 of 3") and no grading between batches.
The author always has an "Other" free-text escape, which is fine.
--free-text: present all questions in one numbered list, then say
"Answer in one reply; number your answers. I won't grade until you're done."
Wait for the author's answers.- Do not proceed to grading until every answer is in.
5. Grade
For each question, in order:
- Verdict: Correct / Partial / Incorrect.
- The model answer in one or two sentences, citing the real
path:line.
- One line on the gap when Partial/Incorrect - what they missed and where to look.
Then a Score (e.g. 6/8, counting Partial as half) and a one-line summary of
the pattern (e.g. "solid on intent, shaky on the error paths").
6. Readiness verdict
End with a clear call:
- Ready for review - understanding is sound; note anything to mention to
reviewers proactively.
- Study first - list the specific files/concepts to re-read before requesting
review, each as a clickable
path:line. Be concrete: "re-read the null handling
in X before you send this out."
Keep it honest - if they'd get grilled in review on something, say so now.
7. If --save
Write pr-quiz/<branch>-scorecard.md: the questions, their answers, your grades
and model answers, the score, and the verdict. Don't commit it unless asked.
Principles
- The author is the examinee, not the collaborator. During the quiz you withhold
answers; you're measuring them, not helping them pass.
- A failed quiz is a successful outcome - it caught a gap before a human's time
was spent. Frame it that way, not as a scolding.
- True to the code. Every question, answer, and grade traces to a line you read.
- Terse and direct in chat - the questions and the verdict, minimal preamble.
