quiz

/tutor:quiz

Test and track understanding with adaptive, code-grounded questions drawn from the onboarding docs' citations.

Preconditions

Check for docs/onboarding/index.md in the repo root. If it does not exist, tell the user to run /tutor:build-study-guide first and stop.

If the file exists, run the Freshness procedure defined in ${CLAUDE_PLUGIN_ROOT}/references/conventions.md. Surface its advisory line verbatim if triggered; otherwise proceed silently.

Read .tutor/progress.md. If it does not exist, create it with the header and table header defined in ${CLAUDE_PLUGIN_ROOT}/references/conventions.md. Parse all existing rows to compute current mastery per topic per layer: a topic is mastered once the mastery rule in ${CLAUDE_PLUGIN_ROOT}/references/conventions.md is satisfied — a cleared (grade ≥ 0.7) evidence: yes row exists for it. Keep this per-topic mastery map in scope for the rest of the session.

Selecting topics

If a specific layer argument was passed, load that layer's NN-<layer>.md doc and quiz only its topics. If all was passed or no layer argument was given, load every layer doc listed in index.md.

Bias selection toward topics with the lowest average grade or no evidence: yes row yet (unmastered topics per the mastery rule). Within that bias, vary the selection order each run so the user cannot predict what comes next. Do not skip mastered topics entirely — revisit them occasionally to confirm retention.

Asking questions

Generation

Generate every question fresh, non-deterministically. Never use a fixed bank of questions. Vary the phrasing, angle, and framing each run even for the same topic. Ground each question in the topic's citations from the layer doc: every question must be answerable by reading the cited file:line range and should not be answerable from general knowledge alone.

Difficulty

Set difficulty according to the --level argument. When --level auto is used (or no level is given), adapt dynamically: start at the difficulty tag on the topic (from the ### heading · _tag_ format in the layer doc), then raise difficulty for topics the user is already passing and lower it for topics where they are struggling.

Evidence questions

At least one third of questions in the session must be evidence-required. For these, give the user the file:line citation explicitly (e.g., "Open model/graph/redis/RedisKGraphWithCache.java:300-360"), then ask something that can only be answered by reading those specific lines — a field name, a return type, a method call order, a constant value. The user's answer must prove they opened the file.

Pacing

Ask one question at a time. Wait for the user's answer before proceeding to the next question. Do not reveal whether the answer is correct until the user has committed to a response.

Grading and recording

Grading

Score each answer 0.0–1.0:

• Reward answers that are specific, grounded, and use language or details that match the cited code.
• Mark directionally correct but vague answers low (0.3–0.5). "It caches something" is not the same as naming the field and its role.
• Set evidence: yes only when the question explicitly required the user to open the cited code AND the answer demonstrates they did (contains file-specific detail that could not be inferred).
• Set evidence: no for conceptual or recall questions even if the user happens to mention a file.

Recording

After grading each answer, append one row to .tutor/progress.md using the table format defined in ${CLAUDE_PLUGIN_ROOT}/references/conventions.md. Use the current UTC timestamp in YYYY-MM-DDTHH:MM format. Do not batch rows — write each row immediately so the log survives an interrupted session.

Mastery

Apply the mastery rule from ${CLAUDE_PLUGIN_ROOT}/references/conventions.md after each row is appended: a topic transitions to mastered when a cleared evidence: yes row exists for it. Update your in-session mastery map accordingly and do not re-quiz a newly mastered topic in the same session unless the user asks.

End-of-session report

When the session ends (user stops or all selected topics have been covered), compare the mastery map at session end to the state it was in at session start. Report:

• Which topics moved from unmastered to mastered this session.
• Which topics improved in average grade but are not yet mastered.
• Which topics showed no improvement or regressed.
• The count of evidence questions asked versus the required minimum (one third of total).

If any topics are still unmastered, suggest running /tutor:quiz <layer> again or /tutor:study <layer> to revisit the underlying material.

Rules

Non-determinism is mandatory. Do not maintain or consult a question bank between sessions. Two runs on the same topic must produce observably different questions. Predictable questions train pattern-matching, not comprehension.

Drive-to-code is the success criterion. A session in which the user never opens a cited file is not a success, regardless of how many verbal answers were correct. If the user has answered several questions without an evidence question appearing, insert one immediately. If the user skips evidence questions or asks you to skip them, decline and explain that evidence questions are required for mastery credit.

See also

• ${CLAUDE_PLUGIN_ROOT}/references/conventions.md — authoritative formats for .tutor/progress.md, the mastery rule, the Freshness procedure, citation syntax, and difficulty tags.