exam-cheatsheet

Purpose

COMPILE (not free-generate) everything already mastered into a dense, printable cram sheet: cheatsheet.md at the workspace root, where every top-level bullet carries a resolvable source link into notebook/, mistakes/, or references/wiki/ — then render it to a PDF at the student's requested page count via the official renderer. Summarize only mastered content. Do not teach new material and do not invent new questions. (walkthrough.md is the retired v3 output name: never write it; leave an existing one untouched.)

Activation

Trigger when all study phases are basically cleared and review is wrapping up, OR when the user asks for 「给我一份考前小抄 / 速记 / 总复习」 (a pre-exam cheat sheet, quick-recall sheet, or final review).

Inputs

• mistakes/ + notebook/ — the HIGHEST-priority compile sources: full mistake entries and persisted walkthroughs/feedback are already student-verified content with ready-made anchors (notebook/chNN.md#<anchor>). Read mistakes/index.md / notebook/index.md first when they exist.
• study_state.json knowledge_window — points with status out_window outrank in_window/verified ones (the student is actively losing those points, and they are exactly what the sheet exists for; status codes per scripts/i18n.py).
• references/wiki/ — core conclusions/formulas per chapter. Iterate through all mastered chapters — from study_state.json's current_phase/phase_checklist when it exists (the structured-state source of truth), else study_progress.md, against study_plan.md — reading each chapter slice one at a time (never dump the whole wiki into context at once) so the sheet covers every mastered chapter.
• references/quiz_bank.json — teacher-flagged key items and their answer frameworks.
• python "${CLAUDE_SKILL_DIR}/scripts/select_hard_questions.py" — ranks example candidates. Resolve it from the skill package root, NOT the workspace (a student workspace has no scripts/). Its output is a FLAT difficulty/mastery-ordered list — grouping by knowledge point is the agent's job (Workflow 3).
• Weak-spot source: study_state.json (mistake_archive / confusion_log / phase_checklist) when it exists — the structured-state source of truth; else study_progress.md (mistakes, confusion entries, per-chapter mastery; a generated view that may be stale). Read mistakes and confusion entries FIRST.

Workflow

1. Load weak spots first. Read mistakes and confusion entries — from study_state.json when it exists, else study_progress.md — before anything else, so the cram sheet prioritizes what the user still loses points on.
2. Extract the skeleton. For each chapter keep only the highest-frequency / highest-scoring formulas, conclusions, and one-sentence term definitions. Drop everything else.
3. One hard worked example per key knowledge point (「例题」). For each mastered chapter run python "${CLAUDE_SKILL_DIR}/scripts/select_hard_questions.py" --workspace <ws> --chapter <N> --mode 查缺补漏 -n <M> --json. Always pass BOTH flags: the explicit --chapter keeps 某章起步补弱 workspaces from fail-louding on a missing range, and the explicit --mode 查缺补漏 overrides a saved 零基础从头讲 mode whose ordering is easy-first — the opposite of what the sheet needs. The output is a flat ranked candidate list, NOT grouped, and the explicit -n matters too: set <M> to at least the item count of references/quiz_bank.json (read its length first; the default is only the top 10, and any cap below the bank size can starve later knowledge points before grouping). From the list, pick the highest-difficulty candidate for each key knowledge point (knowledge points linked to mistake_archive/confusion_log entries come first). A key knowledge point with NO linked bank item gets the explicit mark 「无题库例题」 and keeps only its 「必背结论/公式」+「要点解释」 entries — NEVER invent a question to fill the slot. If the chosen item carries requires_assets=true / maybe_requires_assets=true, the sheet MUST embed ALL its question-side assets (question_context/figure/diagram/table — workspace-relative image links into references/assets/, labeled 题面图 in 中文/双语 or Question-side asset in English); if any needed asset file is missing or unusable, fail-closed — pick a self-contained item for that knowledge point instead. Items whose question_text_status is stub / page_reference are not self-contained either: embed their original-page render from references/assets/ the same way, else swap to a full item. Never put an item whose figure or original page the student cannot see on the sheet.
4. Worked solution (「例题解答」). Substitute the formula with the item's actual values: intermediate arithmetic MAY be skipped, but the base process MUST stay — which formula, what gets substituted, what comes out. When the materials provide no answer, the solution carries ⚠️ AI生成答案，非老师/教材提供.
5. Takeaway (「要点解释」). For each example: how to handle same-type / similar-stem questions — the recognition cue first, then which answer framework to apply.
6. Provenance stays honest, off the layout. Unlabeled lines mean material-sourced — that default applies ONLY to content actually taken from the wiki/materials. Any AI-supplemented line carries 🟡 AI补充，可能与你老师讲的不完全一致 inline; any AI-generated answer carries ⚠️ AI生成答案，非老师/教材提供 inline; a solution whose answer provenance is missing or unknown in quiz_bank.json carries 「来源未知」 explicitly — never let the unlabeled default absorb uncertain provenance (canonical wording in docs/language-policy.md). Per-line 🟢 tagging is no longer required.
7. Traceability is mandatory (lint-enforced). Every top-level - bullet in cheatsheet.md MUST end with a source link of the shape [→](notebook/chNN.md#<anchor>), [→](mistakes/chNN.md#<anchor>), or [→](references/wiki/<file>.md) — prefer the notebook/mistake entry the content was compiled from, falling back to the wiki chapter file. python "${CLAUDE_SKILL_DIR}/scripts/validate_workspace.py" <ws> REDS on any untraced bullet or dead link; run it after writing and fix before showing the student.
8. Write output. Write cheatsheet.md to the workspace root with the four fixed sections per mastered chapter; refresh the progress panel at the end.
9. Render the PDF (page count is the student's call). Ask for the target page count if not stated (default 2). Run python "${CLAUDE_SKILL_DIR}/scripts/cheatsheet_render.py" --workspace <ws> --pages <N>: exit 0 → cheatsheet.pdf produced at exactly N pages with print-safe ≥12 mm margins (never lower them — printers eat edges); exit 3 → no local browser: hand the student cheatsheet.html plus the one-line print instruction the tool emits. Then do a visual pass when the client can view files: open the PDF/HTML — if content overflows the page target or the last page trails more than ~15% blank, nudge --font-size down/up and re-render until the sheet fills exactly N pages as densely as possible.
10. Never invent teacher emphasis that is not in the materials. If the materials do not flag a point, do not present it as a teacher-flagged item.

Output Contract

• Write cheatsheet.md: the four fixed sections per mastered chapter, headings in the active reply language — 中文 「必背结论/公式」→「例题」→「例题解答」→「要点解释」, English Must-memorize conclusions & formulas → Worked example → Worked solution → Takeaway — with a refreshed progress panel at the end. Never write walkthrough.md (retired v3 name).
• Every top-level bullet carries its [→](…) source link (notebook / mistakes / wiki); validate_workspace.py must pass on the written sheet before it is shown.
• Deliver the printable artifact: cheatsheet.pdf at the student's requested page count (default 2) via scripts/cheatsheet_render.py, or cheatsheet.html + print instruction on the no-browser degradation path. Margins stay ≥12 mm; density is tuned with --font-size, never by shrinking margins.
• Provenance is inline and honest: AI-supplemented lines carry 🟡 AI补充，可能与你老师讲的不完全一致; AI-generated answers carry ⚠️ AI生成答案，非老师/教材提供; unlabeled lines are material-sourced (per-line 🟢 tagging not required).
• Student-facing output defaults to English (Simplified Chinese if the student opened in Chinese); a persisted study_state.json language (中文/English/双语) switches it per exam-cram's dispatch rule with single-language purity. (See docs/language-policy.md.)

Language packs

Student-visible wording for this skill lives in per-language packs — load the one matching study_state.json.language BEFORE emitting any student-visible output:

• zh → ../../locales/zh/skills/exam-cheatsheet.md
• en → ../../locales/en/skills/exam-cheatsheet.md
• bilingual → compose from the zh pack with a > EN: mirror line per block (rules in ../../docs/language-policy.md) Unset language → this is the first conversation: the merged first-ask (mode × time budget × language) decides it; default en unless the student opened in Chinese.

Boundaries

• Do not put content into the cram sheet that the materials do not cover unless it is tagged 🟡 or ⚠️.
• The cram sheet is a compression, not a replacement for systematic review, and not a shortcut around the source-labeling and quiz_bank-only rules.