exam-cheatsheet

name	exam-cheatsheet
description	全员通关后把 错题本+笔记本+知识点窗口+wiki 编译成考前速记小抄 cheatsheet.md（每条要点带可溯源 锚点），并在视觉产物模式或用户明确要求 PDF/打印版时按指定页数渲染成打印级 PDF：按「必背结论/公式 → 有难度例题（必要时含题面图）→ 例题解答（代入公式、保留基础过程）→ 要点解释（同类题怎么办）」 四段组织。当复习收尾、用户要「考前小抄/速记/总结/打印版」时使用。
license	MIT

exam-cheatsheet — pre-exam cheatsheet compiler

Purpose

COMPILE (not free-generate) everything already mastered into a dense cram sheet: cheatsheet.md at the workspace root, where every top-level bullet carries a resolvable source link into notebook/, mistakes/, or references/wiki/. Render a PDF at the student's requested page count only when the persisted artifact mode is visual or the student explicitly asks for PDF/print output. Summarize only mastered content. Do not teach new material and do not invent new questions. (walkthrough.md is a retired compatibility filename: never write it; leave an existing one untouched.)

Activation

Trigger when the user explicitly asks for 「给我一份考前小抄 / 速记 / 总复习」 (a pre-exam cheat sheet, quick-recall sheet, or final review), OR when all study phases are basically cleared and review is wrapping up and the persisted artifact mode is visual. An automatically reached final review under chat stays in exam-review as a conversational summary and does not invoke this compiler.

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. Apply the artifact gate before compiling. Read study_state.json.artifact_mode when state exists; missing/legacy/unknown values mean chat. Never infer it from a subscription tier and never ask it as a fourth required first-contact question. Under chat, an automatically reached final review returns to exam-review for a conversational summary and creates no cheat-sheet artifact. An explicit cheat-sheet request under chat may compile cheatsheet.md; only visual or an explicit one-shot PDF/print request may continue to PDF rendering. A one-shot request does not modify the persisted value. No mode authorizes silent dependency or skill installation.
2. 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.
3. Extract the skeleton. For each chapter keep only the highest-frequency / highest-scoring formulas, conclusions, and one-sentence term definitions. Drop everything else.
4. 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 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.
5. 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生成答案，非老师/教材提供.
6. Takeaway (「要点解释」). For each example: how to handle same-type / similar-stem questions — the recognition cue first, then which answer framework to apply.
7. 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.
8. 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.
9. Write output when the gate permits it. Write cheatsheet.md to the workspace root with the four fixed sections per mastered chapter; refresh the progress panel at the end. This step is allowed under chat only for an explicit cheat-sheet request.
10. Render only when PDF/print is authorized. Continue only for standing visual or an explicit one-shot PDF/print request. 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. Under chat without an explicit PDF/print request, do not ask for a page count and stop after the validated Markdown artifact.
11. 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 the retired compatibility file walkthrough.md.
• Every top-level bullet carries its [→](…) source link (notebook / mistakes / wiki); validate_workspace.py must pass on the written sheet before it is shown.
• Under artifact_mode=chat, automatic final review stays conversational; an explicit cheat-sheet request delivers the validated cheatsheet.md but does not render PDF unless that request also asks for PDF/print. Under standing visual, or an explicit one-shot PDF/print request, deliver cheatsheet.pdf at the 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:

• 中文 → ../../locales/zh/skills/exam-cheatsheet.md
• English → ../../locales/en/skills/exam-cheatsheet.md
• 双语 → compose the zh and en packs block by block, zh first with a > EN: mirror (rules in ../../docs/language-policy.md) Aliases such as zh, en, and bilingual are normalized by update_progress.py; do not route on them as stored values. Unset language → the merged first-ask decides it; default English 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.