/exam-tutor

name: exam-tutor
description: >
  按章节惰性加载授课：每次只读当前阶段的一个 wiki 章节，用生活隐喻讲概念、解剖公式；重点题固定走
  题面图→问题→读图量→公式→演算→答案详解→溯源七步，画图题先运行算法。用于讲懂当前章或老师勾出的重点题。
license: MIT

exam-tutor — chapter teaching

Purpose

Teach exactly one current wiki chapter, using metaphors and formula dissection. In zero-basic mode, explain every linked key question with the fixed seven-step walkthrough. Run algorithms before rendering diagrams. This skill teaches; `exam-quiz` alone quizzes and scores.

Activation

Use when `exam-cram` routes the current phase to teaching, or the student asks to learn the current chapter, derive a formula, or explain a key question.

Inputs

• In `processing_mode=lightweight`: one schema-3 visually accepted current-page batch

from `.lightweight/session.json` plus its original pages and declared-scope prompt/answer component assets; no compiled wiki is required.

• `references/wiki/chN_*.md`: the one current chapter; never read the whole wiki.
• `references/teaching_examples.json`: optional examples, read only through the chapter-filtering CLI below; never an answer source.
• `study_state.json`: progress source of truth when present; otherwise the generated `study_progress.md` compatibility view.

Workflow

1. **Load one slice.** Read `study_state.json.processing_mode` first. In `lightweight`, call `lightweight_session.py status`, plan only the current source/page range if it is not already planned, visually inspect those pages, and import the generic item/component manifest with `record-visual`; teach only a schema-3 `visual_ready` batch. A schema-2 `visual_ready` receipt is quarantined read-only: auditably `abandon` it and plan a new attempt, never teach from or silently upgrade it. While still planned, keep `register-answer-dependency` additive; use `set-answer-dependency --reason` to replace/narrow exact answer pages and `remove-answer-dependency --reason` to remove them. Do not call ingestion/OCR, preload later pages, or require a wiki. In `full`, read exactly one current `references/wiki/chN_*.md`. A missing full-mode file means abstain, name it, and never improvise. If full-mode teaching examples exist, run `python "${CLAUDE_SKILL_DIR}/scripts/list_teaching_examples.py" --workspace <ws> --chapter <N> --json` and use only its returned slice. When the full-mode effective cadence below is `step_by_step`, use `--next-pending` instead of loading the whole chapter example slice. A nonzero exit is an invalid/unreadable inventory, not “no examples”; report it.

2. **Teach reproducibly.** Give each concept one concrete metaphor. For STEM, state every formula symbol and unit, then one small hand-computable example. Persist math as `$...$` or `$$...$$`; never leave raw `\frac`, `\sum`, or other TeX as the final reading view.

3. **Use every walkthrough block in order** for every stored/teacher-flagged question and every linked question in zero-basic mode.

**Full-mode pacing:** read the stored preference plus its reported effective and dormant state. `study_state.json.preferences.interaction_style` stores only `batch|step_by_step`; missing legacy state means `batch`. This optional preference is independent from `processing_mode`, `artifact_mode`, and `answer_explanation_mode`, and is not a fourth required startup choice. Persist an explicit change only with `update_progress.py --workspace <ws> set --interaction-style <batch|step_by_step>` (or the strictly validated canonical `--pref interaction_style=...`). It never changes the lightweight page-batch route.

This option applies only to full-mode `teaching_examples.json` items. It does not claim coverage of the chapter bank, typed question units, or the lightweight page-batch route.

• Effective `batch`: use the normal full-mode flow. A true

`preferences.no_questions=true` or any non-full processing mode makes a stored `step_by_step` choice dormant without overwriting it. A stored `batch` choice remains ordinary batch cadence.

• Effective `step_by_step`: call `list_teaching_examples.py --workspace <ws>

--chapter <N> --next-pending --json`. It requires `processing_mode=full`, `no_questions=false`, exact `current_phase`, and valid scoped manifest/state data. It reads the manifest, state, notebook bindings, and baseline within one consistent workspace lock, then returns the first manifest-ordered pending item. A missing manifest, malformed state, or nonzero selector exit blocks the pacing decision; report it and do not guess another item. Two bindings may not share one `notebook_ref`. Only a missing notebook entry or anchor/marker/hash/revision drift may return to pending with bounded stable diagnostics. Link/reparse topology, non-directory/non-regular targets, path escape, invalid UTF-8, an unterminated fence, parse/block corruption, schema/scope/baseline damage, duplicate evidence, and `unexpected_evidence` are fatal. Unbound IDs already present in `phase_evidence[N].teaching_examples` are legal batch/legacy history rather than corrupt step evidence; any ID with a `teaching_example_bindings` record must pass its live notebook-block and manifest-item hash checks regardless of the currently selected cadence. Teach exactly that one item this turn, but complete all seven blocks below; never split one walkthrough across turns. Do not infer progress from notebook presence, language-specific prose, or “I understand” / `Continue`. If `next=null`, `teaching_example_roster_exhausted=true` means only that this full teaching roster has no pending item, including an empty roster; it never completes the chapter or bypasses Guide, bank, typed-unit, asset, checkpoint, or phase gates. A structurally sound current roster with either a stale manifest/notebook binding or an append-only newly added item is a named `usable_with_gaps`