exam-cheatsheet

# exam-cheatsheet — pre-exam cheatsheet compiler

## Purpose
Compile, rather than free-generate, mastered content into workspace-root `cheatsheet.md`. Every top-level bullet must link into `notebook/`, `mistakes/`, or `references/wiki/`. Do not teach new material or invent questions. Render the requested-page-count PDF only for standing `visual` mode or an explicit PDF/print request. Never write the retired `walkthrough.md`; leave an existing copy untouched.

## Activation
Trigger on an explicit request for 「考前小抄 / 速记 / 总复习」, or when review is wrapping up after all phases and persisted `artifact_mode=visual`. Automatic final review under `chat` stays a conversational `exam-review` summary.

## Inputs
- Weak-spot source: `study_state.json` (`mistake_archive`, `confusion_log`, and `phase_checklist`) when it exists; otherwise the possibly stale generated `study_progress.md`. Read these first, then `mistakes/index.md` and `notebook/index.md` when present; their full entries provide preferred ready-made anchors.
- Rank `knowledge_window` status `out_window` above `in_window` and `verified` (codes are defined by `scripts/i18n.py`).
- Read core conclusions and formulas from every mastered chapter in `references/wiki/`, derived from `study_state.json`'s `current_phase`/`phase_checklist` when it exists, otherwise `study_progress.md`, checked against `study_plan.md`. Lazy-load one chapter at a time.
- Use `references/quiz_bank.json` for teacher-flagged items and answer frameworks. Resolve `scripts/select_hard_questions.py` from `${CLAUDE_SKILL_DIR}`, never the student workspace; it returns a flat ranked list which the agent groups by knowledge point.

## Workflow
1. **Gate artifacts.** Read `study_state.json.artifact_mode`; missing, legacy, or unknown means `chat`. Never infer a subscription tier or add a fourth required first-contact question. Automatic `chat` review creates no sheet; an explicit sheet request may create Markdown. Only standing `visual` or an explicit one-shot PDF/print request authorizes rendering. A one-shot request does not modify the persisted value. Never install dependencies or skills silently.
2. **Build the skeleton.** Weak spots come first. Per chapter retain only high-frequency or high-scoring formulas, conclusions, and one-sentence definitions.
3. **Select one hard example per key point.** For each mastered chapter run `python "${CLAUDE_SKILL_DIR}/scripts/select_hard_questions.py" --workspace <ws> --chapter <N> --mode 查缺补漏 -n <M> --json`. Both `--chapter` and `--mode` are required: they avoid a missing-range failure in `某章起步补弱` and override easy-first `零基础从头讲`. Set `<M>` at least to the bank length so the default top ten cannot starve later points. Group the flat result, prioritize points linked to mistakes/confusions, and choose the hardest candidate per point. With no linked bank item, emit 「无题库例题」 and only the 「必背结论/公式」 and 「要点解释」 sections; never invent a replacement.
4. **Fail closed on prompt assets.** For `requires_assets=true` or `maybe_requires_assets=true`, embed every `question_context`, `figure`, `diagram`, and `table` as workspace-relative `references/assets/` links, labeled `题面图` for `zh`/`bilingual` or `Question-side asset` for `en`. Preserve but never embed `student_attempt`; one declaration taints the same physical path across the complete quiz, teaching, and content-unit layers, including a duplicate official-looking declaration. Missing or unusable assets require a self-contained alternative. A `stub` or `page_reference` item likewise needs its original-page render or replacement by a `full` item. Never include an example whose prompt figure/page is invisible. `cheatsheet_render.py` performs the shared three-layer policy and canonical-path gate; do not bypass it with a custom Markdown/image renderer.
5. **Write the four sections.** The worked solution states the formula, substituted values, and result; only intermediate arithmetic may be omitted. The takeaway starts with the recognition cue and then the answer framework. Material-backed lines may remain unlabeled; AI supplements require 🟡 AI补充，可能与你老师讲的不完全一致, AI answers require ⚠️ AI生成答案，非老师/教材提供, and missing/unknown bank answer provenance requires 「来源未知」. Do not let uncertain content inherit the material default; see [`docs/language-policy.md`](../../docs/language-policy.md).
6. **Attach traceability.** End every top-level `- ` bullet with `[→](notebook/chNN.md#<anchor>)`, `[→](mistakes/chNN.md#<anchor>)`, or `[→](references/wiki/<file>.md)`, preferring notebook/mistake evidence. Run `python "${CLAUDE_SKILL_DIR}/scripts/validate_workspace.py" <ws>` and fix every untraced or dead link before delivery.
7. **Write only when authorized.** Create workspace-root `cheatsheet.md` with the four sections for every mastered chapter and a refreshed progress panel. Under `chat`, this requires an explicit sheet request.
8. **Render only when authorized.** For standing `visual` or explicit one-shot PDF/print, ask for the page count if omitted (default 2), then run `python "${CLAUDE_SKILL_DIR}/scripts/cheatsheet_render.py" --workspace <ws> --pages <N>`. Exit 0 must produce exactly N print-safe pages with margins ≥12 mm. Exit 3 returns `cheatsheet.html` plus the emitted print instruction. Visually inspect the result; adjust `--font-size`, not margins, until it fits N pages and the last page has at most about 15% blank. Under ordinary `chat`, stop after validated Markdown and do not ask for page count.
9. Never invent teacher emphasis; only material-flagged points may be described that way.

## Output Contract
- `cheatsheet.md` uses active-language headings per mastered chapter: `zh` uses 「必背结论/公式」→「例题」→「例题解答」→「要点解释」; `en` uses Must-memorize conclusions & formulas → Worked example → Worked solution → Takeaway. Every bullet is traced and validation passes.
- An explicit `chat` request delivers Markdown only unless it also requests print/PDF. Authorized rendering delivers exact-page-count `cheatsheet.pdf`, or `cheatshe