exam-tutor

# 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` mount warning so
     manifest-order re-teaching remains legal. Structural/scope/baseline corruption
     stays `blocked`; the old Guide/completion receipt remain