exam-quiz

Quiz the student from the question bank and grade against stored answers. Never invent questions or answers on the fly.

Purpose

Pull chapter/phase-scoped items from references/quiz_bank.json, present one item at a time across the six quiz types, grade each answer, run the escape hatch on repeated failures, and archive skipped/wrong items (via update_progress.py add-mistake when study_state.json exists, else study_progress.md). Hand control back to exam-cram after the checkpoint.

Activation

• Trigger after a phase is studied and needs a checkpoint quiz, or when the user asks 「测一下 / 来几道题 / 模考」.

Inputs

• references/quiz_bank.json — the question bank. Each item carries type, answer, explanation, source, and a chapter OR phase tag; subjective items carry keywords. Filter selection by chapter or phase. An item with neither tag cannot be selected for a chapter quiz. Items MAY also carry difficulty (1-5) + difficulty_reason written by scripts/score_difficulty.py — an honest heuristic lower bound from structural signals (跨知识点数/结构/需读图/多页解答/章节位置/题型), never a semantic judgement and never per-student; treat the number as an ordering floor, not truth.
• Current chapter number — select only items whose chapter (or matching phase) equals it.

If exam-ingest produced the bank, require every item to carry chapter/phase. Without it, the chapter quiz reports "no items found" even when the bank holds matching items.

Workflow

1. Select & gate items: filter by matching chapter OR phase (the bank uses both fields; filtering on chapter alone drops items tagged only with phase). If the bank contains relevant items, never write new questions.
   • Scope filter (source taxonomy) — the default pool is mixed (all source_types). When the student restricts the range (e.g. 「只做作业题」 = homework-only), record it as a SCOPE FILTER in the progress state and select via it (official tool: python scripts/select_questions.py --workspace <ws> --source-type homework). Items with no source_type tag are EXCLUDED from a restricted scope and their count reported — never silently serve untagged items as if they matched.
   • Explicit scope override — if a later request needs items OUTSIDE the active scope (e.g. homework-only is active but the student asks for lecture figure questions), announce the override BEFORE serving them in the active reply language (中文 「⚠️ 临时覆盖你的 <scope> 范围偏好」 / English ⚠️ Temporarily overriding your <scope> scope preference, substituting the active scope name). A one-turn override never silently changes the recorded scope; ask whether to switch permanently.
   • Difficulty × mastery ordering — when the student wants targeted practice (「挑难题」 / 「先补弱点」 / a mode-driven session), order items with python "${CLAUDE_SKILL_DIR}/scripts/select_hard_questions.py" --workspace <ws> --chapter <当前章> -n <k> (the script resolves from the skill package root — the student workspace has no scripts/; never resolve from cwd) instead of ad-hoc picking. For a checkpoint quiz pass --chapter <当前章> (exact-chapter filter) — select_hard_questions defaults to the whole bank, and --chapter is the ONLY exact-current-chapter scope. Do not use --from-chapter N for a checkpoint: it means every numeric chapter number ≥ N (「所有数值章号 ≥ N」), which pulls in later unstudied chapters; --from-chapter is only for 某章起步补弱 (start from chapter N onward). It combines the bank's difficulty (scored by ${CLAUDE_SKILL_DIR}/scripts/score_difficulty.py; if unscored it computes on the fly, no write) with the student's study_state.json mastery (错题/疑难 → weak, 窗口外 → weak, 在窗口/已实测 → mastered) and honors the learning mode: 查缺补漏 serves weak-first 先易后难 then mastered 先难挑战; 零基础从头讲 is globally 先易后难. It honors the recorded scope (study_state.scope, untagged excluded per the scope-filter contract; --source-type all overrides to the mixed pool for one turn AFTER you announce the override); 某章起步补弱 requires an explicit --chapter or --from-chapter (it never guesses a chapter from current_phase). Deterministic heuristic ordering — no LLM ranking; the visual-first asset gate and scope filter below still apply to every item it returns.
   • Visual-first asset gate (fail-closed) — before asking an item, apply the single runtime contract in docs/file-format.md §4:
     • For requires_assets=true or maybe_requires_assets=true: before asking, explaining, hinting, or solving, actually render/show every question-side asset (question_context / figure / diagram / table) inline and label it per §4 in the active reply language (中文/双语 题面图, English Question-side asset). Merely printing the file path is not enough; the student must see the prompt image.
     • Use only question-side assets at first. Do not show answer-side assets (answer_context / worked_solution) before the question-side assets; show them only during solution/review and label them per §4 in the active reply language (中文/双语 答案图, English Answer-side asset).
     • Do not ask the item if any required question-side asset is missing, unreadable, unrenderable in the current UI, or only available as a non-rendering path — say the item is blocked because the prompt asset cannot be shown, then pick another safe full item if one is available.
     • Prefer workspace-relative Markdown paths such as references/assets/...; never emit malformed slash-prefixed Windows drive-letter links, and never claim an image was displayed if the link did not render.
     • If question_text_status is stub or page_reference: do not treat the text as a complete standalone question — surface the prompt asset or original page first. If neither can be displayed (no asset, original not in the workspace, or web/no-image), skip it rather than asking a question the student cannot see.
2. Grade by the six quiz types:
   • choice — compare against the answer option.
   • subjective — keyword-coverage grading: pass if the answer covers the item's keywords and key steps; accept equivalent wording; report coverage feedback.
   • fill_blank — compare against the standard fill (accept synonyms).
   • true_false — compare the verdict and require a one-line reason.
   • code — check the key edits/output against answer.
   • diagram — do not judge the figure from memory: follow render_hint to run the standard algorithm first, derive the structure, then compare against the student's drawing; state that the instructor's drawing method takes precedence.
3. Escape hatch: on a wrong answer, give the logic gap + the item's explanation + a hint. On the 2nd consecutive wrong answer, offer three choices — view hint / skip and archive the wrong item / continue — and proceed per the choice.
4. Archive: record skipped or wrong items — with study_state.json, run python "${CLAUDE_SKILL_DIR}/scripts/update_progress.py" --workspace <ws> add-mistake --id <qid> --chapter <ch> --note <错误原因> (the script resolves from the skill package root — the student workspace has no scripts/; never resolve from the current directory) (hand-editing the generated md loses the row on the next render); without state, write into the study_progress.md wrong-item archive.
   • Persist-first (notebook CLI) — each graded item's full feedback (verdict, logic gap, explanation, source block) is written to the notebook BEFORE the chat reply: echo <feedback body> | python "${CLAUDE_SKILL_DIR}/scripts/notebook.py" --workspace <ws> add-entry --chapter <ch> --type feedback --id <qid> --title <question gist> (body via STDIN; same --id replaces in place; notebook/index.md rebuilds). For a wrong or skipped item, ALSO pass --mistake — it mirrors the entry into mistakes/chNN.md and rebuilds mistakes/index.md; this mirror is IN ADDITION to the update_progress.py add-mistake state row above (the state row and the notebook entry index each other), never a replacement for it. The chat reply is a short digest ending with the pack-provided link line (zh 「完整反馈：notebook/chNN.md#<anchor>｜目录：notebook/index.md」, en Full feedback: notebook/chNN.md#<anchor> | Index: notebook/index.md). On a failed notebook write, TELL the student and give the full feedback in chat; file-less clients keep chat-only output per exam-cram's capability dispatch.
5. Source honesty + per-item source block: when an item's or answer's source is ai_generated, flag it at grading time with the full AI-generated provenance sentence in the active reply language (中文 「⚠️ AI生成答案，非老师/教材提供」 / English ⚠️ AI-generated answer — not from your teacher or textbook; reference only, verify against the instructor/textbook). Additionally, after grading EVERY item, emit the fixed one-line source block in the active reply language — 中文 题目来源：<文件名> 第<N>页（<source_type>）｜答案来源：<文件名/老师·教材提供/AI 推导（无教材答案）>｜<canonical 溯源标签>, English Question source: <file> p.<N> (<source_type>) | Answer source: <file p.N / teacher-provided / AI-derived (no textbook answer)> | <label> — the trailing label is exactly one of the three canonical provenance sentences in the active reply language (中文 🟢 来自资料 / 🟡 AI补充，可能与你老师讲的不完全一致 / ⚠️ AI生成答案，非老师/教材提供 — English the three EN sentences in docs/language-policy.md). When the answer is AI-supplied (no stored / textbook answer), the label MUST be the full ⚠️ sentence AND the 解析/参考答案 block title carries it. Missing source metadata → write 中文 「来源未知」 / English Source unknown (Source page unknown when only the page is missing), never fabricate a filename or page. Same contract as exam-tutor's teaching template.

Output Contract

• Present one item at a time; grade as pass/not-pass plus key-point feedback; refresh the progress panel at the end.
• Persist-first default: grading feedback is written to notebook/chNN.md (--type feedback) before the chat reply, and wrong/skipped items carry --mistake so the entry ALSO lands in mistakes/chNN.md alongside the add-mistake state row (Workflow step 4); the chat reply is a digest plus the pack-provided link line. On a failed write, say so and deliver full feedback in chat; file-less clients keep chat-only output.
• Each graded item's feedback ends with the one-line source block, rendered per the active reply language (中文 题目来源：…｜答案来源：…｜<🟢/🟡/⚠️ 标签> / English Question source: … | Answer source: … | <label>) (Workflow step 5); an AI-supplied answer carries ⚠️ in both the 解析/参考答案 block title and the source label.
• Update the check-in log and wrong-item archive — via update_progress.py (add-mistake / set-check) when study_state.json exists, else in study_progress.md — then hand control back to exam-cram.
• Student-facing output defaults to English (Simplified Chinese if the student opened in Chinese); a persisted study_state.json language (中文/English/双语) switches it per exam-cram's dispatch rule with single-language purity. (See docs/language-policy.md.)
• Provenance labels in feedback follow the active reply language (中文 verbatim markers 🟢 来自资料 / 🟡 AI补充，可能与你老师讲的不完全一致 / ⚠️ AI生成答案，非老师/教材提供 — English the three EN canonical sentences in docs/language-policy.md).

Language packs

Student-visible wording for this skill lives in per-language packs — load the one matching study_state.json.language BEFORE emitting any student-visible output:

• zh → ../../locales/zh/skills/exam-quiz.md
• en → ../../locales/en/skills/exam-quiz.md
• bilingual → compose from the zh pack with a > EN: mirror line per block (rules in ../../docs/language-policy.md) Unset language → this is the first conversation: the merged first-ask (mode × time budget × language) decides it; default en unless the student opened in Chinese.

Boundaries

• Structured progress state: when study_state.json exists it is the SINGLE SOURCE OF TRUTH — update it via python "${CLAUDE_SKILL_DIR}/scripts/update_progress.py" --workspace <ws> set/add-mistake/add-confusion/render (script path resolves from the skill package root); study_progress.md is a GENERATED view (hand edits are lost on the next render — never hand-patch it). If a state write fails, TELL the user; never continue as if it saved. Without study_state.json but WITH Python (a fresh, uninitialized workspace), run update_progress.py --workspace <ws> init to create the source of truth FIRST — do not stop at hand-editing study_progress.md; only when Python truly cannot run does a hand-maintained md stay valid.

• When the bank holds relevant items, do not write your own. With no stored answer, do not force a verdict — mark ⚠️ or state the limitation plainly.

• Do not judge diagram items from memory — the algorithm-derived standard structure is the reference.

• Fail-closed on assets: never ask an item whose requires_assets=true or maybe_requires_assets=true when a required question-side asset is missing, unreadable, or cannot be displayed (e.g. web-only). A blocked item is skipped, not improvised — choose a full-text item instead. The validator (scripts/validate_workspace.py) rejects a workspace whose visual-required item lacks valid question-side asset files, so a clean workspace won't reach you in that state.

• Use the official visual tools instead of ad-hoc parsing: to emit a visual item's prompt-side image Markdown deterministically, run python <package-root>/scripts/show_question_assets.py --workspace <ws> --id <qid> --lang <zh|en> (pass the active reply language; it fail-closes with exit 1 when the contract can't be met — then skip the item). When the student asks visual statistics (e.g. "which chapter has the most figures"), answer on both metrics — quiz-bank visual items (scripts/list_image_questions.py, per-chapter total × requires × maybe × suspects) AND material figure pages (scripts/list_figure_pages.py) — and say which metric is which; if image_question_index.json is missing, build it first via scripts/build_visual_index.py rather than counting by hand.