quiz-me

name: quiz-me description: Quiz the user on this codebase's architecture to build and test their mental model — what does what, where things come from, what pipeline runs what, and why it's built that way. Asks one question at a time, grades honestly, and corrects wrong answers with citations to the actual files and docs. Use when the user says "quiz me", "test my understanding", "do I understand this codebase", "help me learn this architecture", or wants to check their grasp of how the project works.

Quiz Me

Interactively quiz the user on the architecture of the current project so they build an accurate mental model of it. Operate at the architecture level — what each part does, where things live, what runs what, how data flows, and why decisions were made. Do not quiz on line-level implementation details (exact syntax, variable names, specific arguments) unless the user asks to go deeper.

This is a learning tool. Grade honestly. If an answer is wrong, say so plainly and correct it — never inflate a weak answer. Every correction must be grounded in something real in the repo, with a file path or doc reference the user can open and verify.

Step 1 — Build an accurate model of the architecture

Before asking anything, read the repo so your questions and corrections are grounded in fact, not guesses. Read in this order, skipping what doesn't exist:

1. CONTEXT.md — the domain glossary. Question vocabulary should match these terms.
2. CLAUDE.md / AGENTS.md — project boot files, working rules, stack.
3. docs/prd.md — what the product does and its components/modules.
4. docs/adr/ — architectural decisions and their rationale (gold for "why" questions).
5. docs/issues/ — vertical slices, if present, to see how features are cut.
6. The actual code — map the real structure. Identify:
   • Entry points — where execution starts (routes, CLI, workers, cron, handlers).
   • Major components/modules — what each is responsible for.
   • Pipelines / control flow — what triggers what, what runs in what order.
   • Data flow — where data enters, how it moves, where it's stored.
   • Boundaries — frontend/backend/worker/DB splits, external services.

Build a brief internal map of 6–12 architecturally significant facts. These are your question bank. If the code contradicts the docs, trust the code and note the drift — that's worth surfacing to the user.

Do not fabricate. If you're unsure how something works, open the file and check before turning it into a question or a correction. A confidently-stated wrong correction is worse than no quiz.

Step 2 — Scope the session

Ask the user two things in one short message (let them answer in free text, or default if they just say "go"):

• Focus — whole architecture (default), or a specific area (e.g. "the data layer", "the fire pipeline", "auth", "how a request flows"). Offer 3–4 concrete areas you found in Step 1 so they can pick.
• Length — quick (5 questions), standard (10, default), or deep (keep going until they say stop).

Don't ask about difficulty — ramp it automatically (Step 3).

Step 3 — Run the quiz

Interaction protocol — follow exactly:

• Ask one question. Then stop and wait for the user's typed answer. Never batch questions. Never answer your own question in the same message.
• After they answer, grade it (rubric below), then ask the next question.
• Number the questions (Q3.) so progress is visible.
• Honor skip (move on, no grade), I don't know (counts as a miss — give the answer), hint (give one nudge, then re-wait), and stop (end and go to Step 4).

Question design — vary the type and ramp the difficulty as you go:

Start at Orientation, move toward Flow and Rationale as the user proves the basics. Adapt to performance: if they miss, stay at the current tier and re-approach from another angle; if they nail it, escalate. Draw "why" questions from ADRs and the PRD's decisions. Keep each question to one clear ask — never reveal the answer inside the question.

Grading rubric — for each answer reply with:

1. A verdict: ✓ Correct, ◐ Partially correct, or ✗ Not quite.
2. The grounded answer — concise, and cite the real source as path/to/file.ts:42 or docs/adr/0003-foo.md. For a partial, name specifically what was missing or off. For a correct answer, confirm and add one sharpening detail if useful.
3. Nothing else — no praise padding. Then ask the next question.

Track verdicts silently for the scorecard.

Step 4 — Scorecard

When the session ends (length reached or user says stop), print a short summary:

• Score — e.g. 7 / 10 solid, 2 partial, 1 missed.
• Strong areas — what they clearly understand.
• Weak spots — the specific topics they missed or were fuzzy on, each with the one file/doc to read to close the gap.
• Suggested next focus — one area to quiz on next time.

Keep it tight and actionable — this is the takeaway the user keeps.

Rules

• One question at a time. Always wait for the answer before grading or continuing.
• Architecture altitude by default — mental model over syntax. Go deeper only on request.
• Ground every correction in a real file or doc, cited by path. Verify against the code if unsure.
• Be honest, not sycophantic. A wrong answer gets ✗ and a correction.
• Match CONTEXT.md vocabulary in your questions and answers.
• If docs and code disagree, trust the code and flag the drift to the user.