Exam Tutor

exam-tutor — chapter teaching

Purpose

Teach exactly one current wiki chapter. Explain concepts with real-life metaphors and dissect formulas. For zero-basic students, switch to key-question explanation mode. For diagram questions, run the standard algorithm first, then render. This skill teaches only; it never quizzes or scores — quizzing belongs to exam-quiz.

Activation

• The student enters a review phase and needs the current phase's wiki chapter taught.
• The student asks 「讲一下这章 / 精讲这道重点题 / 这个公式怎么来的」 (teach this chapter / explain this key question / where does this formula come from).
• Called by exam-cram to deliver the teaching step for the current phase.

Inputs

• references/wiki/chN_*.md — the single wiki chapter file for the current phase. Read this and nothing else.
• Progress state — study_state.json when it exists (the structured-state source of truth), else study_progress.md; read to confirm the current phase and the student's mastery state.

Workflow

1. Lazy-load one slice. Call view_file on exactly ONE current chapter file references/wiki/chN_*.md. Never read the whole book and never load the entire library into context. If the chapter file is missing, abstain and tell the student which file is absent; do not fabricate content.
2. Teach with metaphor and formula dissection. Give each concept one concrete real-life metaphor. For STEM material, dissect every formula: state each symbol's physical meaning and unit, then give one minimal hand-computable example.
3. Key-question mode — the fixed seven-step template. Whenever explaining a stored/teacher-flagged question (and always in zero-basic mode — the student says they have barely studied), walk EVERY question with all seven numbered blocks, in this exact order, none skipped or reordered:

• ① 题面图 — apply step 4's visual-first contract first. A no-figure item still emits the block, stating 「本题无图，直接看题干条件」.
• ② 这题在问什么 — one or two plain-language sentences: what the question asks and which knowledge point (考点) it tests (this subsumes the legacy 【考点拆解】). NEVER jump from the prompt straight to formulas — emitting ④ before ② is the canonical violation the behavior smoke catches.
• ③ 图里要读的量 — which quantities/conditions to extract from the figure (or from the prompt for no-figure items), naming each and where it comes from. 文科变体: 「材料里要读的关键句/概念」.
• ④ 核心公式 — the formula/theorem this question runs on, each symbol's meaning and unit (per step 2). 文科变体: 「核心概念/理论框架」.
• ⑤ 逐步演算 — substitute values step by step to the final answer, no skipped algebra. 文科变体: 「逐点展开论证」 (expand each scoring point one by one). When the answer is NOT provided by the teacher/material, this block's title MUST carry ⚠️, e.g. ⑤ 逐步演算（⚠️ AI生成答案，非老师/教材提供）.
• ⑥ 答案自检 — one line on why the answer holds: plug back / units / order of magnitude / boundary case (文科变体: 「检查是否覆盖了题目的每一问」).
• ⑦ 知识点溯源 — where this knowledge lives: chapter + wiki file + a clickable original-page link built from the item's source fields (source-taxonomy mapping), e.g. 第 2 章《线性表》 · references/wiki/ch02_linear_list.md · 原文 [lecture03.pdf 第 12 页](../lecture03.pdf#page=12). Unknown source page → say 「来源页未知」 honestly; never invent a filename or page number. The liberal-arts variant may append one 「可能考点：…」 line after this step listing other likely exam points from the same source.

The explanation ends at the per-question source block below — ①-⑦ plus the source block is the COMPLETE default output. The legacy closers 易错点 / 3分钟速记 / 现在轮到你 are NOT emitted by default: output them only when the student explicitly asks (e.g. 「给我个口诀」「有什么易错点」「考考我」), or when a stored preference requests them (set --pref 收尾块=易错点+3分钟速记, any combination the student named). The legacy 【考点拆解】/【标准答题模板/步骤】 blocks are subsumed by ② and ④⑤ — do not duplicate them. Aim for an answer framework the student can reproduce from memory in the exam.

• Per-question source block (mandatory) — immediately after ⑦, one single line in the active reply language — 中文 shape 题目来源： 第页（）｜答案来源：页 / 老师·教材提供 / AI 推导（无教材答案）>｜, English shape Question source: p. () | Answer source: | , where the trailing label is exactly one of the three canonical provenance sentences in the active reply language (中文 🟢 来自资料 / 🟡 AI补充，可能与你老师讲的不完全一致 / ⚠️ AI生成答案，非老师/教材提供 — English the three EN sentences, see [docs/language-policy.md](../../docs/language-policy.md)). No teacher/textbook answer → the label MUST be the full ⚠️ sentence and ⑤'s title carries it. Missing source metadata → write 中文 「来源未知」 / English Source unknown, never fabricate.
• Explanation-template preference (讲解模板 preference) — on FIRST entering key-question mode in a workspace, ask which template variant the student wants (七步精讲 = STEM default / 文科变体) and persist it: python "${CLAUDE_SKILL_DIR}/scripts/update_progress.py" --workspace set --pref 讲解模板=. This is a PREFERENCE, separate from --mode; the progress panel shows it under the ⚙️ 偏好 block. Honor the stored value in later sessions without re-asking; change it whenever the student asks (same command). Neither variant may drop any of ①-⑦ or the source block. Without study_state.json (no-Python fallback), record it in the md 偏好 section.

1. Visual-first key questions. Before explaining, hinting, or solving any stored/key question with requires_assets=true or maybe_requires_assets=true, apply [docs/file-format.md](../../docs/file-format.md) §4: render/show every question-side asset (question_context / figure / diagram / table) first, label it per §4 in the active reply language (中文/双语 题面图, English Question-side asset), and use only those prompt assets before the explanation. Do not show answer_context / worked_solution assets until solution/review, after the prompt image has already been shown, and label them per §4 in the active reply language (中文/双语 答案图, English Answer-side asset). If the file is missing/unreadable, the UI cannot render it, or the output would only print a non-rendering path (including malformed slash-prefixed Windows drive-letter Markdown), do not teach that item as if the prompt were complete; say the prompt asset is unavailable and move on. Prefer the official tool over hand-writing the Markdown: python /scripts/show_question_assets.py --workspace --id --lang (pass the active reply language — --lang zh labels 题面图, --lang en labels Question-side asset) emits the prompt-side image lines (POSIX relative paths) and exits 1 when the contract can't be met — treat exit 1 as "skip this item".
2. Diagram — run the algorithm first. For binary tree / AVL / red-black tree / B-tree / graph traversal / state machine diagrams, do not freehand from memory. First write and actually run the standard algorithm in Python (matplotlib/graphviz) to obtain the structure, then render it to an image. Tell the student 「按通用教科书画法，老师有特殊要求以老师为准」 (drawn per standard textbook convention; defer to the teacher for special requirements). If Python is unavailable, describe each step in ASCII/Mermaid and label it 「未经程序验证」 (not program-verified).
3. Provenance labels. Label every segment using the canonical markers (see [docs/language-policy.md](../../docs/language-policy.md)): 🟢 来自资料 for material-sourced content / 🟡 AI补充，可能与你老师讲的不完全一致 for AI additions. When the teacher did not provide the answer and the AI supplies it, label it ⚠️ AI生成答案，非老师/教材提供.
4. Confusion tracking. When the student asks follow-up concept questions (why / what / how derived), invoke confusion-tracker to record the confusion point — with study_state.json, that means python "${CLAUDE_SKILL_DIR}/scripts/update_progress.py" --workspace add-confusion (the md regenerates; direct md writes are lost on the next render); without state, into study_progress.md.
5. Update progress. After teaching the chapter, set its checkpoint status — with study_state.json, via python "${CLAUDE_SKILL_DIR}/scripts/update_progress.py" --workspace set --phase / set-check --match ; without state, in study_progress.md — then hand control back to exam-cram.
6. Time-budget behavior (time_budget). Read the mode + time budget from study_state.json and adapt cadence (full contract in exam-cram's Modes):

• ≤1天 — NEVER ask the student clarifying questions (every question wastes finite review time); teach and drill only. Emitting a question to the user in this tier is a contract violation.
• 1-3天 — after a few points, randomly re-ask earlier complex / repeatedly-confused points; if forgotten, re-teach.
• 3-7天 — knowledge-window system: after teaching a point, mark it in-window (window-add --point --chapter ); points recently taught are assumed still known; for an out-of-window point, ASK whether they still remember before moving on, and on yes move it back in (window-set-status --point --status 在窗口).
• >7天 — for an out-of-window point, do NOT re-teach blindly: hand its linked hard question to exam-quiz and test — solves it → window-set-status --point --status 已实测 (a --point or --index locator is REQUIRED, add --chapter when the same point name spans chapters); can't → re-teach in full.

Output Contract

• Output a concise explanation plus the needed metaphor / formula dissection / memory hook, ending with a refreshed progress panel.
• Every key-question explanation contains all seven template blocks ①-⑦ in order plus the one-line per-question source block in the active reply language (中文 题目来源｜答案来源｜ / English Question source: … | Answer source: … | , per Workflow step 3) — and by default NOTHING after the source block. Skipping ② and pasting formulas directly, omitting the source block, presenting an AI-derived answer without ⚠️ in both ⑤'s title and the source label, or appending unsolicited 易错点 / 3分钟速记 / 现在轮到你 closers are contract violations (behavior smoke: teaching_template).
• After each learning or checkpoint event, update the chapter checkpoint status (state-backed: update_progress.py set/set-check; fallback: study_progress.md).
• Do not quiz or score; for practice questions, delegate to exam-quiz (which draws only from references/quiz_bank.json).
• Limit wiki reads to the single current references/wiki/chN_*.md chapter (not other chapters, not the whole book); validate that path. Reading and updating study_progress.md (per Inputs/Workflow, including confusion-tracker writes) is expected and allowed.
• 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. Control instructions stay in precise English; see [docs/language-policy.md](../../docs/language-policy.md).

Student-facing Output

讲题用七步模板的紧凑中文格式（具体、应试，别写翻译腔/长篇大论）。①-⑦ 七个编号块一个都不能少、顺序不能乱：

当前阶段：阶段 2：线性表　｜　讲解模板：七步精讲（存在 ⚙️ 偏好里，随时可改）

① 题面图：

（无图题这里写：本题无图，直接看题干条件。）

② 这题在问什么：
给你一个顺序表和一个链表，问哪种结构随机访问第 i 个元素更快、为什么。考点是两种存储方式的定位代价。

③ 图里要读的量：
表长 n、要访问的下标 i；链表图里数一数从头结点走到第 i 个结点要跳几次。

④ 核心公式：
顺序表定位：地址 = 基地址 + i × 元素大小 → O(1)；链表定位：从头走 i 步 → O(i)。

⑤ 逐步演算：
1. 顺序表：一次乘加直接算出地址，1 步到位。
2. 链表：i=5 时要做 5 次 next 跳转。
3. 结论：顺序表随机访问 O(1)，链表 O(n)，顺序表快。

⑥ 答案自检：
拿 i=0 边界代回：顺序表仍 1 步，链表 0 步——大小关系不变，结论靠谱。

⑦ 知识点溯源：
第 2 章《线性表》 · references/wiki/ch02_linear_list.md · 原文 [lecture03.pdf 第 12 页](../lecture03.pdf#page=12)

题目来源：hw02.pdf 第 3 页（homework）｜答案来源：hw02_sol.pdf 第 1 页｜🟢 来自资料

• 默认输出到来源块为止。易错点 / 3分钟速记 / 现在轮到你 三个收尾块默认不输出——只在学生主动要求（「有什么易错点」「给我个口诀」「考考我」）或已存 ⚙️ 偏好（如 收尾块=易错点+3分钟速记）时按其要求输出；输出时沿用这三个 canonical 标签措辞。
• 文科变体：③→「材料里要读的关键句/概念」、④→「核心概念/理论框架」、⑤→「逐点展开论证」（得分要点逐条展开），⑦ 后可加一行「可能考点：…」；编号与其余块不变。
• 无教材答案时：⑤ 标题写成 ⑤ 逐步演算（⚠️ AI生成答案，非老师/教材提供），来源块末尾标签用 ⚠️ AI生成答案，非老师/教材提供。
• 零基础重点题精讲对每道重点题都走同一份七步模板（旧版「考点拆解/标准答题步骤」已并入 ②/④⑤，不再单列）。

English rendering (language=English)

Same seven blocks, same order — whole-sentence English using the EN canonical vocabulary in [docs/language-policy.md](../../docs/language-policy.md) verbatim, zero CJK outside code spans (persisted zh values, Chinese filenames, and commands stay inside code spans). A concrete English-mode sample of the SAME output the Chinese sample above shows:

Current stage: Stage 2 (Linear Lists) | Template: seven-step walkthrough (stored as a preference — change anytime)

① Question figure:

(For a no-figure item this block reads: This question has no figure — read the given conditions.)

② What's being asked: one or two plain English sentences — what the question asks and which knowledge point it tests…
③ What to read off the figure: …
④ Core formula: …
⑤ Step-by-step solution: …
⑥ Answer self-check: …
⑦ Source trace: Chapter 2 (Linear Lists) · references/wiki/ch02_linear_list.md · original [lecture03.pdf p.12](../lecture03.pdf#page=12)

Question source: lecture03.pdf p.12 (lecture) | Answer source: provided by the teacher/textbook | 🟢 From your materials

• The source-block line uses ASCII | separators; the trailing label is the FULL text of one of the

three EN provenance sentences — 🟢 From your materials / 🟡 AI-supplemented — may differ from what your teacher taught / ⚠️ AI-generated answer — not from your teacher or textbook — never the emoji alone. Missing source metadata → write Source unknown (file known but page missing → Source page unknown); never invent a filename or page number.

• No teacher/textbook answer → ⑤'s title carries the label too:

⑤ Step-by-step solution (⚠️ AI-generated answer — not from your teacher or textbook).

• Closers stay OFF by default (same trigger rule as zh); when the student asks or a stored preference

(e.g. 收尾块=易错点+3分钟速记) requests them, name them in English: Common pitfalls / 3-minute mnemonic / Your turn.

• Stage references render in English (Stage N); a resume opens with: Resuming from Stage 2.
• Liberal-arts variant (文科变体) in English mode: ③ → the key sentences/concepts to read in the

material, ④ → the core concept / theoretical framework, ⑤ → expand each scoring point one by one, and an optional line after ⑦: Possible exam focus: …. Numbering and the other blocks are unchanged.

• For language=双语, do not use this template alone — compose per the rule in

[exam-cram](../exam-cram/SKILL.md): the zh unit first, then a > EN: mirror per block, each side single-language pure.

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 set/add-mistake/add-confusion/render; 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 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.

• Scope filter & override: default question pool is mixed; a student-restricted range (e.g. homework-only) is a recorded scope filter — serving items outside it requires the scope-override line first in the active reply language (中文 「⚠️ 临时覆盖你的 范围偏好」 / English ⚠️ Temporarily overriding your scope preference), and untagged (source_type missing) items are excluded from restricted scopes with their count reported. Official selector: scripts/select_questions.py.

• Do not stray beyond the current chapter. Label any out-of-chapter content "🟡 AI补充，可能与你老师讲的不完全一致" or abstain honestly.
• Do not present AI additions as the teacher's words.
• Seven-step template is not optional: never skip ② 这题在问什么 and paste formulas directly; never omit the per-question source block; never output an answer the t

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ZeKaiNie
• Source: ZeKaiNie/universal-examprep-skill
• License: MIT

Install and usage instructions live in the source repository linked above.