exam-cram

# 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