Exam Cram Coach

Purpose

Coordinate last-minute exam prep. Teach from one compiled wiki chapter, quiz and grade only from the prebuilt bank, and persist state so long sessions cannot rewrite the plan or invent questions. Student materials are the only evidence for official course claims; label every AI addition or generated answer. Route concrete work to the subskills listed below.

Activation

Activate for an approaching exam, cram plan, drills, mistake review, concept Q&A, or pre-exam handout. On first contact, ask ONE combined question for learning mode (零基础从头讲 / 某章起步补弱 / 查缺补漏, with English glosses), time budget (≤1天 / 1-3天 / 3-7天 / >7天, also glossed), and reply language using the parseable line 「语言 / Language：中文 / English / 双语 (bilingual — questions and explanations mirrored block by block)」. Persist all three together. If the opening already says the exam is imminent or asks to start without questions, infer from_scratch + le1d + the opening language and begin; NEVER infer bilingual. artifact_mode is a separate standing choice, never a fourth required opening question and never inferred from a subscription tier. Legacy normal|sprint|panic|mock values are migration-only. Do not activate outside exam prep.

Startup processing choice

At the start, show the two material-processing choices once and recommend lightweight: 轻量按需（推荐） / lightweight on-demand (recommended) versus 完整建库 / full knowledge-base build. Persist the canonical choice as study_state.json.processing_mode=lightweight|full. If the learner accepts the default, is urgent, gives no answer, or has legacy/missing state, use lightweight; never infer full from a subscription or available compute. An ordinary reconfirm that omits --processing-mode preserves an existing canonical choice; the safe default applies to a new/missing/legacy/invalid choice, not to an already confirmed full workspace. Keep this choice independent from artifact_mode=chat|visual.

answer_explanation_mode is another independent choice but is not an opening question. Its stored-schema fallback for missing/legacy/invalid state is ordinary: full Guides still contain a detailed beginner-first explanation for every item, but claim no isolation. At full-v2 Guide entry, run a native-child capability handshake. If the host can prove one fresh independent child context per item and can restrict that child's task input and tools to the exact request, default to isolated unless the learner opted out. Persist the mode, tell the learner once that it consumes extra host model quota/time, and require no separate API key or external-upload consent. If any part is missing, inherited, or unverified, stay ordinary and say why. A separately billed external Provider is an explicit-request fallback only; it retains no-upload exact planning, current pricing/privacy disclosure, and exact-plan upload consent. A model name, subscription, key, full, or visual alone proves neither native isolation nor permission to upload.

Teaching cadence is another optional, independent preference, not an opening question. preferences.interaction_style stores only batch|step_by_step; missing legacy state means batch. A stored step_by_step choice is effective only when processing_mode=full and no_questions=false; lightweight or no-questions keeps the preference but reports it dormant and uses effective batch. Effective step mode reads the next teaching item in manifest order from one workspace-locked snapshot and records a marker-bound notebook/manifest hash binding. Existing unbound teaching IDs remain legal batch history, but every bound ID stays subject to live validation after any cadence change. Guide publication preserves valid bound blocks and rejects stale bindings or unbound markers; every retained teaching baseline ID must still have a current teaching-manifest snapshot, never only a quiz copy.

Teaching IDs use the existing typed Guide-safe Unicode contract (1–200 characters, without whitespace, controls/replacement character, or []#|`/\). A structurally sound append-only roster expansion or live-binding revision drift reopens an old completed phase as usable_with_gaps; structural damage remains blocked, and the Guide/completion receipt must be rebuilt after the pending item is recorded.

Inputs

• Confirmed, separate materials and workspace paths.
• study_state.json (progress truth), generated study_progress.md, and study_plan.md.
• One current references/wiki/chN_*.md plus selected items from references/quiz_bank.json; never preload either collection.
• .ingest/ structured build/review truth, when present.

Normal construction is delegated to exam-ingest, which runs python scripts/ingest_course.py --materials <dir> --workspace <ws> --json. ingest.py is only the lower-level compiler for an existing payload; never ask the student to author JSON.

processing_mode=lightweight uses the original materials directly and does not require .ingest/, compiled wiki/bank files, or a typed Study Guide. It keeps learning truth in study_state.json and page-batch truth in .lightweight/session.json. processing_mode=full delegates construction to exam-ingest as before.

Workflow

Run these gates before routing any learning action:

1. Confirm the exact workspace. Run python "${CLAUDE_SKILL_DIR}/scripts/update_progress.py" workspace-list --json. An empty registry requires materials path, separate target path, the three learning choices, and an optional 30-second tour. A nonempty registry requires choosing the exact saved course/path and filling missing choices. Never silently use the repository or cwd. After confirmation, use the single write gate:

   python "${CLAUDE_SKILL_DIR}/scripts/exam_start.py" confirm --course <course> --materials <dir> --workspace <ws> --mode <mode> --time-budget <tier> --language <zh|en|bilingual> --processing-mode <lightweight|full> [--artifact-mode chat|visual] [--answer-explanation-mode ordinary|isolated] [--urgent] --json

   Omit --answer-explanation-mode during ordinary startup confirmation; omission preserves an existing canonical choice, while new/legacy/invalid state safely resolves to ordinary. At full-v2 Guide entry, the capability handshake above may persist native isolated; an external fallback may persist it only after its separate consent gate.

   --urgent may infer only mode and budget; the caller supplies the opening language. Use exam_start.py status ... --json for read-only checks. Lightweight requires ready_to_start=true; the separate ready_to_ingest=true gate is intentionally false until processing is explicit full. Every opening panel shows the absolute workspace path.

2. Route by the persisted processing choice. In lightweight, do not call ingest_course.py, parser/OCR adapters, retrieval builders, Study Guide authoring, HTML/PDF rendering, or LangGraph. Initialize once with python "${CLAUDE_SKILL_DIR}/scripts/lightweight_session.py" init --materials <dir> --workspace <ws> --json, which safely creates the workspace-local .lightweight/assets/ output directory; never require the host to create that directory as an undocumented prerequisite. Then plan only the current phase's PDF pages or one standalone raster, at most eight pages per batch and with at most one planned|visual_ready batch. In full, a workspace missing wiki, bank, or state/progress routes to exam-ingest; do not teach while its result says readiness=blocked.

3. Restore state first. Restore from study_state.json when it exists. If absent and Python works, immediately run update_progress.py --workspace <ws> init; hand-maintain Markdown only when Python truly cannot run. Continue the requested action after restoration.

4. Validate structured content. When .ingest/ exists, run python "${CLAUDE_SKILL_DIR}/scripts/validate_workspace.py" <ws> --json on mount and after ingest/review. blocked forbids teaching, quizzes, and completion and returns to the typed review queue; usable_with_gaps proceeds only after naming every warning. Legacy workspaces keep the compatibility route.

5. Lazy-load and show assets first. Read only the one current chapter and needed bank/example slice. For requires_assets=true or maybe_requires_assets=true, before routing into teaching, asking, hints, explanation, or solving, render every question-side question_context / figure / diagram / table asset and label it 题面图 or Question-side asset. Show 答案图 / Answer-side asset only later in solution/review. Preserve but never display student_attempt; its physical path is globally tainted across quiz, teaching, and all content units, so a duplicate official declaration cannot restore it. Route stored items through scripts/show_question_assets.py or the selected subskill's equivalent three-layer validator and honor a nonzero result; never render a raw path as a shortcut. A printed path is not an image; if the UI cannot render it, skip/stop the item. Apply the same rule to stub and page_reference prompts. See docs/file-format.md §4.

After the gates, choose one route:

• Teaching: delegate one chapter to exam-tutor. Persist every walkthrough. In explicit full, build and validate/import the current profile=full typed guide before phase completion; chat stops at that typed gate, while standing visual or a one-shot artifact request delegates rendering and all-page QA to exam-study-guide and requires artifact_ready=ready. Lightweight never enters either typed Guide or artifact rendering.
• Quiz: delegate selected current-chapter bank items to exam-quiz; choice, subjective, diagram, fill-blank, true/false, and code are supported. No usable item means no verifiable checkpoint and a covered_unverified cap—NEVER invent a substitute. Compute diagram structures before rendering them.
• Concept Q&A: answer from the current chapter and send why/what/how-derived confusion to confusion-tracker.
• Two wrong attempts: offer hint / skip and archive / continue.
• Final review: trigger when all study phases are cleared, judged from study_state.json's current_phase/phase_checklist (or the legacy view) against study_plan.md, or when explicitly requested. A fresh student teaches first. Load mistakes and confusions, then use exam-review. Automatic review under chat stays conversational; explicit cheat-sheet creation may write Markdown, while PDF still needs visual or an explicit print/PDF request and delegates to exam-cheatsheet.

After each learning/checkpoint event, update with python "${CLAUDE_SKILL_DIR}/scripts/update_progress.py" --workspace <ws> set/add-mistake/add-confusion/set-mistake-status/set-confusion-status/record-phase-evidence/record-taught-example/complete-phase/set-check and refresh the panel. Use record-taught-example only for effective full step mode as defined above; batch teaching evidence stays on record-phase-evidence. File-less clients use a copyable text breakpoint.

Modes

Initial values are persisted together by exam_start.py confirm; later changes use one update_progress.py set --mode ... --time-budget ... --language .... Canonical codes are from_scratch|shore_up|fill_gaps, le1d|d1_3|d3_7|gt7d, and zh|en|bilingual.

• 零基础从头讲: start at chapter 1; cite every point, then walk all linked items easy-to-hard once; hard items feed the cheat sheet.
• 某章起步补弱: known chapters get a point list and one hard example per point; unknown chapters expand as zero-basic; add examples at confusion.
• 查缺补漏: list every chapter's points once, with one hard example each; expand only gaps.

Time modifies cadence, never source/asset/bank safety:

• ≤1天: no opening clarification/preference or reflective follow-up; start. This does not forbid bank-backed drills or checkpoints. Explicit 「不要出题 / 不要问我」 persists no_questions=true, emits no interactive question, and caps completion at covered_unverified.
• 1-3天: occasionally recheck difficult or repeated-confusion points and reteach forgotten ones.
• 3-7天: persist recently taught points with window-add; ask whether an out-of-window point is remembered before window-set-status ... --status 在窗口.
• >7天: verify an out-of-window point using its linked hard bank item; pass marks 已实测, fail reteaches fully.

Window state lives in study_state.json.knowledge_window; a point/index locator is required and cross-chapter names also need chapter. Deprecated modes migrate as follows: panic→zero-basic+one-day, sprint→fill-gaps+1–3 days, normal/mock→fill-gaps. mock is quiz cadence, not a mode.

Material processing

study_state.json.processing_mode is lightweight or full:

• lightweight is the default and recommended path. Run lightweight_session.py status, then plan --chapter <N> --source <relative-file> --pages <range> only when the learner reaches that topic; <N> must equal current_phase, sources are limited to PDF or definitely single-frame PNG/JPEG/BMP, a batch is at most eight primary pages, and only one batch may remain active. If the learner continues after this phase was already marked complete, the same plan transition must recoverably reopen the completion record; never leave an active batch hidden behind a stale completed badge or hand-edit the progress view. Ask the host's native visual/PDF capability to render and inspect only those pages. A single-page work order has no contact sheet. For multiple pages, overview contact sheets group at most four pages and must partition the primary batch exactly once, at roughly 768 px per row-major tile. Each sheet is consumed once by an overview call. New visual receipts use schema 3: enumerate stable teaching_item_ids on every primary page and define each item as text|figure|mixed with generic prompt/answer components. Each component declares its role, sorted required context IDs, exact allowed detected IDs, and a source-qualified crop. Context-only components are allowed, but at least one prompt component must visibly contain the target. A detail call may combine prompt components only for one target; a solution call may combine answer components only for one target. Every component gets an independent one-crop crop_review model call whose detected IDs exactly equal its declared target/context scope and which proves no unrelated content or student attempt. Geometry or a filename is not semantic evidence. If an official answer is elsewhere, run register-answer-dependency --batch-id <id> --source <relative-file> --pages <range> while the batch is planned. This is additive. Use set-answer-dependency ... --pages <exact-range> --reason <reason> to replace/narrow a binding or remove-answer-dependency ... --reason <reason> to remove it; both are audited and exact retries are idempotent. Every primary/dependency page declares content types and answer_provenance. Dependency pages are answer locators/detail inputs and never enter a solution call; only an official_solution parent may produce an answer component, and every registered official-solution page must be covered by one. Student-attempt/unknown pages remain inspectable but cannot satisfy answer evidence. Model-call rows bind exact host/model, asset path/hash, and source-qualified source ID/path/revision/page locations; bare page numbers are insufficient and an asset cannot be reused across ordinary stage calls. A contact sheet never replaces a page or prompt component. Every canonical page, dependency-page, contact, prompt, and answer evidence file is PNG with matching magic bytes and measured dimensions under .lightweight/assets/, never under or reused from a full-build asset path. Page images are at least 480×480 and item crops at least 64×64. Every component crop is distinct; answer components remain hidden until solution/review. Import the receipt with record-visual, teach in full beginner-friendly detail, persist the exact notebook/chNN.md#entry-anchor, then use mark-taught --taught-item-ids <exact-comma-separated-IDs>. It revalidates source/visual/notebook bindings, separates inspected pages from taught item scope, and publishes the taught receipt plus phase_evidence[phase].lightweight_batches under the workspace lock; a retry idempotently repairs a taught-first interruption. Never shorten teaching output to save input tokens. Lightweight completion requires all current-phase batches taught and a one-to-one live event set, skips typed Guide/full-build evidence, and may reach covered_unverified. At first init, preserve an immutable stat-only baseline for any pre-existing standard bank without parsing or hashing it. Only an explicit quiz/checkpoint opens the bank and binds the exact bank/item revision. verified still requires two distinct revision-bound handled items from that unchanged pre-existing baseline and one pass; an absent-at-init, replaced, or drifted bank and legacy unbound checkpoint rows cannot qualify. Never invent a scored quiz. Schema-2 visual receipts remain immutable history. A legacy active schema-2 visual_ready attempt is quarantined from recording/teaching and may only be auditably abandoned before a new schema-3 attempt. If an unfinished scope must be closed, run abandon --batch-id <id> --reason <concrete-reason> on its planned|visual_ready batch. The hash-bound abandonment receipt remains in the ledger and a replacement plan becomes a new attempt. A taught batch is durable progress and cannot be abandoned. If it must be redone, replace-taught --batch-id <id> --reason <concrete-reason> retains its receipts, notebook binding, and progress event as immutable superseded history and opens a planned successor for the exact same primary slice; it revalidates dependency revisions while preserving their exact page sets. The predecessor/event stays auditable but is excluded from the current completion denominator. Routine status takes a generation-stable read-only snapshot without creating or opening a lock for writing; workspace validation performs metadata plus physical-identity checks only. Exact stream hashes are recomputed only by plan, dependency registration/replacement/removal, record-visual, mark-taught, phase completion, or explicit status --verify-live. Non-current taught history keeps immutable receipt/progress-event consistency checks and is counted as unchecked_historical until that phase becomes current again. Read status_schema_version=2 and answer_taint_contract_version=2 before interpreting the machine status fields. Read full_page_answer_taint_status only as a conservative fact about the uncropped locator/detail page. Read answer_taint_status, item_crop_review_status, and teaching_publication_status as the separate item-crop teaching verdict; a parent page containing a student attempt does not relabel clean reviewed crops plus an official answer crop as blocked.
• full is explicit opt-in. It opens ingest_course.py and the validated structured build/review route. It still does not imply artifact_mode=visual and does not authorize a PDF without that separate explicit choice.

To switch modes, use update_progress.py --workspace <ws> set --processing-mode lightweight|full, then rerun exam_start.py confirm so the runtime/start receipt describes the selected route. Switching to lightweight does not delete a prior structured workspace; it only forbids eager rebuilds and uses existing current artifacts lazily when they remain valid. Reconfirming later without a processing flag preserves this canonical choice.

Artifact output

study_state.json.artifact_mode is chat or visual:

• chat is the safe default for missing/legacy/unknown values: conversation plus notebook/state, with no automatic chapter HTML/PDF or cheat-sheet PDF.
• visual persists only after an explicit choice via update_progress.py ... set --artifact-mode visual; it requests typed manifest → render → receipt → every-page QA. Delivery and completion require artifact_ready=ready. Failure stays blocked/degraded. It never permits silent installation.

The stored preference remains independent from processing intensity. Under processing_mode=lightweight, even a stored visual is reported as artifact_mode_preference=visual, artifact_mode_effective=chat, and artifact_mode_dormant=true; it becomes active only after an explicit switch to full. A one-shot Guide request likewise requires that switch rather than bypassing the lightweight boundary.

An explicit return uses set --artifact-mode chat. A one-shot request temporarily overrides chat without changing the stored preference. Never inspect or infer a subscription tier. A language change stales prior-language manifests/artifacts; re-author/import and, when visual output is requested, rerender and repeat all-page QA.

Output Contract

• Persist substantive walkthroughs, grading feedback, confusion explanations, and review conclusions first with scripts/notebook.py add-entry; wrong/skipped items also use --mistake. Then send a 3–5 line digest plus the language-pack notebook link. A failed write is reported and the full content stays in chat. Only progress panels, the static help card, and one-shot escape hints are exempt; file-less clients use chat/text breakpoints.
• Dispatch student prose from study_state.json.language with SINGLE-LANGUAGE PURITY: zh is pure Simplified Chinese; en is pure English using canonical vocabulary (default if unset unless the opening was Chinese); bilingual mirrors each zh block under > EN:. Machine IDs, keys, hashes, enums, statuses, and reason codes remain stable. Original-language evidence may remain only when explicitly labelled; agent prose still follows the selected language.
• Be concise and conclusion-first. End every reply with localized subject/current-stage/progress/mistake fields.
• Use the full canonical provenance sentences: 🟢 来自资料 / 🟢 From your materials; 🟡 AI补充，可能与你老师讲的不完全一致 / 🟡 AI-supplemented — may differ from what your teacher taught; ⚠️ AI生成答案，非老师/教材提供 / ⚠️ AI-generated answer — not from your teacher or textbook. Unsupported answers always carry the full ⚠️ label. If materials give no basis, say 「资料里没有这道题的答案」 or “The materials do not contain an answer to this question.”

Heavy capability boundary

Never download, install, import, or execute MinerU, Docling, or LangGraph in the student's local environment. The lightweight route never offers them. A full-mode learner must explicitly request a named heavy capability before it can be proposed, and execution must occur in a host-supplied remote/cloud service with separately confirmed upload/privacy terms. If the active host has no such remote integration, say it is unavailable and stay on native visual/core review; an installed local package is not permission to use it. Workspace files and study_state.json, not a remote workflow checkpoint, remain the state truth.

Language packs

Load the selected pack before student-visible output:

• 中文 → ../../locales/zh/skills/exam-cram.md
• English → ../../locales/en/skills/exam-cram.md
• 双语 → compose both blockwise, zh then > EN:, under docs/language-policy.md

Display aliases are normalized to zh|en|bilingual; unset language is decided by the combined first ask.

Boundaries

• study_state.json is the single source of truth. Write it only through python "${CLAUDE_SKILL_DIR}/scripts/update_progress.py" --workspace <ws> ...; study_progress.md is generated. Fail writes loudly. With Python, initialize missing state; direct Markdown maintenance is true no-Python fallback only.
• Default question scope is mixed. A recorded restricted scope excludes/counts items without source_type. Before a one-turn override say 「⚠️ 临时覆盖你的 <scope> 范围偏好」 / ⚠️ Temporarily overriding your <scope> scope preference.
• Ordinary selection uses scripts/select_questions.py. Checkpoints use python "${CLAUDE_SKILL_DIR}/scripts/select_hard_questions.py" --workspace <ws> --chapter <current> --mode <mode> -n <k>. --chapter is exact; never replace it with --from-chapter, which means all numeric chapters ≥N and is only for shore_up. Cross-chapter practice may omit the chapter only when explicitly requested. The selector combines structural difficulty from score_difficulty.py with mistake/confusion/window state, respects stored scope, and requires explicit chapter/from-chapter for shore_up.
• Stay within student materials; label supplements or abstain. Never claim what the teacher said, contact teacher/registrar, invent bank replacements, lecture from memory without the wiki, or disguise AI as material.

Subskills: exam-ingest builds/reviews; exam-tutor teaches; exam-study-guide validates typed guides and, when requested, renders/QA; exam-quiz selects/grades; exam-review replays mistakes/confusions; exam-cheatsheet compiles final handouts; exam-audit is read-only; exam-help is the quick card; confusion-tracker records confusion. Root SKILL.md remains the compatibility entry and AGENTS.md the compact generic-agent fallback.