zekainie/universal-examprep-skill/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.

1. 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.

1. 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 remains ineligible. Teaching IDs use the shared 1–200-character Guide-safe Unicode contract; keep an incompatible source-facing label in source/title metadata instead of changing a stable ID. If the ID alone produces an empty Markdown slug, the notebook entry needs a descriptive title. Every retained baseline ID must have a current teaching snapshot in the same canonical chapter under exact policy=append_only`; a quiz-only copy cannot substitute.

For each active question to be explained:

• ① 题面图: satisfy the visual gate in step 4 first; without a figure say 「本题无图，直接看题干条件」.
• ② 这题在问什么: explain the ask and 考点 in plain language. Never jump from the prompt to ④.
• ③ 图里要读的量: name each condition/quantity and its location; humanities variant: 「材料里要读的关键句/概念」.
• ④ 核心公式: formula/theorem plus symbol meanings and units; humanities: 「核心概念/理论框架」.
• ⑤ 逐步演算: substitute and derive without skipped algebra; humanities: 「逐点展开论证」. If no teacher/material answer exists, the title must be ⑤ 逐步演算（⚠️ AI生成答案，非老师/教材提供）.
• ⑥ 为什么这个答案成立: use the current item as the only course-item context and explain the supplied answer for a zero-prerequisite student—connect the ask to each quantity/concept, define every symbol/rule, show substitutions/reasoning, cover every subquestion, and state what the result means. If the prompt/answer is insufficient or inconsistent, say so instead of inventing facts. Do not add a generic answer-self-check panel.
• ⑦ 知识点溯源: chapter, wiki path, and clickable original location from source fields. Unknown location must say 「来源页未知」; never invent it. Humanities may append one 「可能考点：…」 line.

Immediately after ⑦, end with one source line in the active language: 题目来源：<文件/页/source_type>｜答案来源：<材料位置/老师·教材提供/AI 推导（无教材答案）>｜<canonical label> or Question source: <file/page/source_type> | Answer source: <...> | <label>. Missing metadata says 「来源未知」 / Source unknown. The label is exactly one canonical sentence from `docs/language-policy.md`: 🟢 来自资料; 🟡 AI补充，可能与你老师讲的不完全一致; or ⚠️ AI生成答案，非老师/教材提供 (and its English counterpart). With no material answer, both ⑤ and this line carry the full ⚠️ sentence.

The seven blocks plus source line are the complete default. 易错点 / 3分钟速记 / 现在轮到你 appear only when requested or stored in 讲解模板; legacy 【考点拆解】 and 【标准答题模板/步骤】 are already covered by ② and ④⑤ and must not be duplicated.

Honor a stored 讲解模板 preference. If absent and the tier is not ≤1天, ask once for 七步精讲 (STEM default) or 文科变体, then persist it with python "${CLAUDE_SKILL_DIR}/scripts/update_progress.py" --workspace <ws> set --pref 讲解模板=<七步精讲|文科变体>. In the ≤1天 tier, asking is forbidden: immediately use 七步精讲 for STEM or 文科变体 for clear non-STEM and persist that inferred default silently. Neither variant may remove a block or source line. If state is absent and Python works, initialize it first; only a true no-Python fallback may write the generated view.

Persist before replying: pipe the complete walkthrough to python "${CLAUDE_SKILL_DIR}/scripts/notebook.py" --workspace <ws> add-entry --chapter <N> --type walkthrough --id <qid> --title <gist>. Omit --lang to inherit the canonical zh|en|bilingual value from study_state.json, or pass that same value explicitly; never store a bilingual body under a fake zh override. Quiz/teaching/notebook/Guide IDs share the safe-Unicode 1–200-character contract; if the ID alone generates an empty Markdown slug, supply a descriptive title. The same chapter/id replaces in place and rebuilds notebook/index.md. For effective full-mode step_by_step, add --teaching-example; this writes a reserved ID-bound marker. After that succeeds, use only update_progress.py --workspace <ws> record-taught-example --id <qid> --notebook-ref notebook/chNN.md#<anchor>. The command validates full/effective-step mode, the current first-pending manifest item, exact anchor, walkthrough type, matching ID, and marker, then atomically stores the ID/notebook evidence plus exact teaching_example_bindings fields id, notebook_ref, notebook_block_sha256, and manifest_item_sha256. Unbound IDs remain legal batch history; a bound event must continue to pass live notebook/manifest validation after cadence changes. Never replace this with two loose record-phase-evidence writes. Acknowledgement/Continue is routing input only, never completion evidence. Guide notebook publication must leave a live-valid bound marked block unchanged; it fails closed rather than rewriting a stale binding or a marked block without a valid binding. Then reply with a 3–5 line digest and the language-pack link. In effective step_by_step, append the active-language continuation wording after the digest, outside the persisted walkthrough; under le1d it must be a non-reflective continue/reteach prompt, and an unstored style must not trigger a preference question. In bilingual mode, render the Chinese continuation line followed by its pure-English > EN: mirror; either language's Continue command routes one next turn and never creates duplicate evidence. If either write fails, report it and do not claim the item complete; a failed notebook write must be followed by the full chat content. File-less clients use chat plus a text breakpoint.