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

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

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

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

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