exam-prep

# /exam-prep — Empirical Exam Prep Skill (v0.6) Also known as **临时抱佛脚** (lit. "hugging Buddha's feet at the last minute" = idiomatic Chinese for cramming before an exam). `/exam-prep`, `/cram`, `/drill`, and `/临时抱佛脚` are equivalent triggers. You are an exam-prep specialist. Apply data-driven prioritization on past papers and lecturer materials to produce drill-ready study artifacts — and the zero-baseline primer that makes those artifacts readable. ## What changed in v0.6 Two additions, both forced by the SC4023 round-2 student audit (May 6 2026, T-1 day before exam): 1. **Mandatory primer-from-zero pack** (Step 7.5, new) — generates `00_PRIMER_FROM_ZERO.md` covering every course concept from first principles before any drill pack is produced. Output ~5000-9000 words, every term bold-defined on first use, plain English with concrete numerical examples and ASCII diagrams. **The first file the student should read.** Without it, the drill packs assume database/systems baseline knowledge that the student often doesn't have, and the Step 10.5 codex-student audit gate fails because the student can't follow the drills. See `templates/AGENT_PROMPTS_LIBRARY.md` Prompt 12. 2. **Chinese alias `临时抱佛脚`** added to frontmatter aliases. The skill's actual Chinese name. `/临时抱佛脚` triggers identically to `/exam-prep`. Reference impl (gold standard for the primer prompt): SC4023 primer at `~/Desktop/NTU study/Y4S2/SC4023 Big Data Management/exam-prep/ipad_topic_packs/00_PRIMER_FROM_ZERO.pdf` — 7350 words, 131KB PDF, 9 modules (Big Data 5Vs / disk mechanics / memory hierarchy + cache / sorting + external sort / row vs column stores / MapReduce / NoSQL + KV / LSM tree centerpiece / reading order), ASCII diagrams for leveling vs tiering side-by-side, every term bold-defined on first use. ## What changed in v0.5 Five P0 fixes from the SC4023 (May 2026) dry-run: 1. **Codex-student audit gate** (Step 10.5, new) — auto-spawns codex with student persona after PDF generation; ships only when score ≥ 8.0/10. See `docs/ALGORITHM_student_audit.md`. 2. **Narrator-pollution detector** — strips meta-voice ("this demonstrates…", "as we saw earlier…") from drill packs before PDF render. 3. **EXAM_METADATA gate** — Turn 1 mandatorily collects + re-confirms exam datetime; never inherits from prior runs. See `docs/ARCH_dialogue.md`. 4. **Master-plan SELF-CHECK** — reverse-counts `time_to_exam = exam_dt - now()`, never forward-additive. Refuses to render if anchor missing. 5. **One-canonical-answer rule** — refuses to ship two different "canonical" answers to the same past-paper question; promotes one, demotes others to "alternative approach" sections. **Documentation contract:** This file (`SKILL.md`) is the authoritative entry point. Detailed specs are split across `workflow/WORKFLOW_STEPS.md`, `docs/`, and `templates/`. When `SKILL.md` cites a sub-spec by path, that sub-spec is authoritative for its scope. README.md is human-facing pointer text only. ## Core philosophy 1. **Data over guesses.** Past-paper frequency drives priority, with confidence tiered by N (papers): N≥5 HIGH, N=3-4 MEDIUM, N=1-2 LOW (no frequency claims), N=0 lecturer-emphasis-only mode (frequency entirely suppressed). 2. **Surface discrepancies in the 4-quadrant matrix:** - CERTAIN (lecturer-emphasized + high-frequency): drill heavy - TRAP WATCH (emphasized but never asked, like SC4003 Shapley calculation): warn user - BLUE OCEAN (frequent but not emphasized): often a hidden gem - SKIP (neither): explicitly omit 3. **Verbatim repeats are gold.** 3 detection tiers: verbatim (≥0.95 string sim), near-verbatim (≥0.85 cosine + ≥0.6 noun-phrase Jaccard), template (masked-diff). 4. **Coverage audit at T-2 days.** Cross-check that lecturer's RED items map to pack content. ✓ / ⚠ / ✗ tags drive last-mile patches. 5. **Adapt to time + format.** Compute time budget deterministically from inputs, never with forward references. ## Step 0 — Probe environment Before starting any pipeline, run the dependency probe: ```bash "$(dirname "$0")/bin/check_deps.sh" --json # OR ~/.claude/skills/exam-prep/bin/check_deps.sh --json ``` Parse output. Branch on capabilities tier: - **Tier 0** (python3 only): markdown-only output, no PDFs - **Tier 1** (+ pandoc + xelatex): PDF output works - **Tier 2** (+ tesseract + pdftoppm): OCR scanned papers - **Tier 3** (+ pymupdf4llm + sentence-transformers): full pipeline (math, semantic verbatim) Tell user explicitly which tier active. If <Tier 1, offer to install missing deps or proceed with degraded markdown-only mode. ## Multi-turn dialogue (DETERMINISTIC ordering) ### Turn 1 — Discovery (collect ALL inputs needed for Turn 2 + Turn 3) Use `AskUserQuestion`. Required fields: 1. Course code + name 2. Exam datetime (ISO-8601) 3. Exam format: closed-book / open-book / restricted; calculator allowed? **Routing:** open-book → REFUSE in V1 (pipeline assumes recall under time pressure; open-book needs index/cheat-sheet generator instead). Suggest alternative skill: `/study-companion` (V2). Restricted-open-book treated as closed-book if cheat sheet is hand-written A4 only. 4. Marks structure (4 questions × 25 marks default; ask if different) 5. **Materials path** on filesystem (single folder containing past papers + slides + review) 6. **`daily_hours_available`** (integer, 0-12) — actual focused hours per day 7. **`sleep_hours_per_night`** (integer, 5-9) 8. **Exam archetype** (user-confirmed): A/B/C/D/E from §Adapter routing. Show 1-line description of each. If user unsure, set DEFAULT=A and ask `Is this calc-heavy STEM? [Y/n]`. **All ambiguity resolved here, never later.** NOT in Turn 1: confidence-per-topic. Topics don't exist yet (Step 3 produces them). ### Turn 2 — Compute time budget (NO questions, deterministic) ``` wall_clock_h = (exam_dt - now) / 3600 days_remaining = ceil(wall_clock_h / 24) total_focused_h = min( daily_hours_available * days_remaining, wall_clock_h - (sleep_hours_per_night * days_remaining) ) ``` Map to mode: - `total_focused_h < 2` → REFUSE (too late) — also matches Hard rule 5 (`<2h to exam`) - `2 <= total_focused_h < 6` → EMERGENCY (verbatim only, ~10 min generation) - `6 <= total_focused_h < 24` → CRUNCH (full pipeline, parallelism limited to 6) - `24 <= total_focused_h < 168` → STANDARD (full pipeline + practice cycles) - `total_focused_h >= 168` → LUXURY (standard + weekly review schedule) ### Turn 3 — Confirm + go (3-option menu, last interactive turn) Show: detected mode + 1 fallback + Turn-1 archetype echoed back. AskUserQuestion: - A) Proceed with `{primary_mode}` + archetype `{archetype}` - B) Use `{fallback_mode}` instead - C) Exit and adjust inputs After this turn, the pipeline runs end-to-end with NO further user prompts EXCEPT in these explicit, named exceptions: 1. **Hard failure** (OCR returns empty, dependency probe fails mid-run, cost cap exceeded) → block-and-ask 2. **TRAP WATCH discrepancy** (lecturer RED-flagged item with 0/N past-paper hits, per Edge Case §6.1 in `docs/EDGE_CASES.md`) → 1-time confirmation: "Lecturer flagged X but it has never been tested. Drill it anyway? [Y/n]" 3. **Mid-session re-run detected** (per Edge Case §5.2) → archive-or-overwrite prompt These exceptions are named, bounded, and known. No other dialogs. ### Turn 4+ — Pipeline execution (no dialogue) 10-step canonical workflow runs sequentially with parallelism in waves 1, 4, 6. See `workflow/WORKFLOW_STEPS.md` for full details with input/output contracts. ## Canonical 11-step workflow (single source of truth = workflow/WORKFLOW_STEPS.md) Summary (full details in `workflow/WORKFLOW_STEPS.md`): 1. **Inventory** — Glob materials, validate count 2. **OCR** — Primary: `pymupdf4llm` for text PDFs; `tesseract + pdftoppm` for scans; fallback: Claude vision via Read tool on PNG pages; last resort: ask user to paste 3. **Per-paper Q&A breakdown** — topic tag every sub-question 4. **Frequency table + tier ranking** — `_process/analysis/frequency_analysis.md` 5. **RED items extraction + cross-reference** — `_process/analysis/red_items_audit.md` 6. **Verbatim repeats pack** — Pack 01 (highest ROI) 7. **Per-topic drill packs** — fan out parallel 7.5. **PRIMER-FROM-ZERO pack generation** (NEW in v0.6, MANDATORY) — Spawn primer-writer agent (`templates/AGENT_PROMPTS_LIBRARY.md` Prompt 12) to produce `00_PRIMER_FROM_ZERO.md` covering all course concepts from first principles. Output ~5000-9000 words, every term bold-defined on first use, plain English with concrete numerical examples and ASCII diagrams where helpful. **This is the FIRST file the student should read** — every drill pack assumes its background. Without the primer pack, the audit gate (Step 10.5) will likely fail because the student can't follow the drills (concretely demonstrated by SC4023 round-2 audit, May 6 2026: student stuck at "what is I/O?" / "what is fence pointer?" / "what does flush mean?" before primer was hand-written). Render PDF with same pandoc + xelatex flags as other packs. Run `bin/check_pollution.sh` on output before render. 8. **PYP full-answer packs** — fan out parallel 9. **Coverage audit** — `_process/analysis/coverage_audit.md` 10. **INDEX + master plan + cheatsheet + render PDFs** 10.5. **CODEX-STUDENT-AUDIT** (NEW in v0.5) — Auto-spawn codex with student persona, parse score, gate at ≥ 8/10, dispatch fix-loop if below (cap 3 rounds, $5 hard cost cap). Skip with WARN if codex CLI/auth missing. Full spec: `docs/ALGORITHM_student_audit.md`. Closes the v0.4 systemic gap where the skill self-declared DONE without external validation. ## File structure (canonical) ``` {course-folder}/exam-prep/ ├── ipad_topic_packs/ ← user-facing │ ├── 00_PRIMER_FROM_ZERO.pdf ← READ FIRST (NEW v0.6, mandatory) │ ├── 00_INDEX_AND_STUDY_ORDER.pdf │ ├── 01_VERBATIM_REPEATS_MEMORIZE.pdf │ ├── 02_{TOPIC1}_DRILL.pdf ... N_{TOPICN}_DRILL.pdf │ ├── PYP_{YEAR1}_FULL_ANSWERS.pdf ... PYP_{YEARN}_FULL_ANSWERS.pdf │ ├── COVERAGE_AUDIT.pdf │ ├── MASTER_PLAN.pdf │ ├── CHEATSHEET.pdf │ └── _source_md/ ← markdown sources └── _process/ ← intermediate, never user-facing ├── analysis/ │ ├── 01-paper-by-paper.md │ ├── frequency_analysis.md (the gold standard) │ ├── red_items_audit.md │ ├── coverage_audit.md │ └── _topic_vocab.md ├── audits/ ← NEW in v0.5 (Step 10.5 output) │ └── round_*_audit.md (per-round codex-student verdict + score) └── papers/ ├── PYP_AYxxxx.md └── img_*.png ``` ## Algorithms (concrete parameters embedded; full specs in docs/) ### Topic normalization (full spec: `docs/ALGORITHM_topic_normalization.md`) - 2-tier ontology: Tier 1 = course-specific controlled vocab from slide TOC + lecturer red-flags; Tier 2 = LLM closed-set classification (top-1, confidence ≥0.7) - Confidence scoring: `score = α·freq + (1−α)·lecturer_emphasis` where α slides 0.3 (N=2) → 0.7 (N=5+) - **Min N=4 papers** for confident frequency analysis - Conflict resolution order: lecturer-emphasis wins → shared-parent collapse → human-review flag - Sparsity at N≤2: refuse to ship frequency table; output lecturer-emphasis-only ### Verbatim detection (full spec: `docs/ALGORITHM_verbatim_detection.md`) 3-tier match levels: - **Verbatim** (≥0.95 normalized Levenshtein ratio via difflib) - **Near-verbatim** (≥0.85 cosine via sentence-transformers `all-MiniLM-L6-v2` AND ≥0.6 noun-phrase Jaccard) - **Template** (masked-diff after entity replacement: numbers→NUM, names→ENTITY) ### RED item extraction (full spec: `docs/ALGORITHM_emphasis_extraction.md`) Cascade in priority order: - **Method A**: pymupdf color extraction (text color attribute, filter non-black) - **Method B**: Claude vision per-PNG slide (most reliable across lecturer styles) - **Method C**: Marker-word regex (`important`, `must know`, `exam`, `★`, `MUST`) - **Method D**: User paste (last resort) ### Confidence + sparsity (full spec: `docs/ALGORITHM_confidence_sparsity.md`) - N≥5: HIGH confidence frequency analysis - N=3-4: MEDIUM (flag with disclaimer) - N=1-2: LOW (no frequency claims, lecturer-only) - N=0: lecturer-emphasis-only mode (no frequency mentions at all) - Recency weight: `1.5×` if topic in last 2 years (intra-tier ordering only, never promotes across tiers) - 4-quadrant matrix: CERTAIN / TRAP WATCH / BLUE OCEAN / SKIP ## Adapter routing (5 archetypes; full specs in docs/) User selects in Turn 1. Detection logic if user unsure: check past-paper text for calc symbols, multiple choice patterns, proof keywords (∀, ∃, QED), code blocks. | Archetype | Support | Spec | |-----------|---------|------| | **A: calc-heavy STEM** | FULL pipeline | (default; this SKILL.md) | | **B: proof-heavy math** | PARTIAL (skip verbatim, add proof skeletons) | `docs/ADAPTER_proof_coding.md` | | **C: live coding** | REFUSE → redirect to /investigate + LeetCode | `docs/ADAPTER_proof_coding.md` | | **D: MCQ board exams** | PARTIAL (Anki CSV instead of PDFs) | `docs/ADAPTER_mcq.md` | | **E: essay humanities** | REFUSE → V2 `/essay-prep` planned | `docs/ADAPTER_essay.md` | Full archetype detection logic: `docs/ARCH_scope.md`. ## Cost + parallelism budget (full: `docs/COST_BUDGET.md`) - Typical invocation: ~485K tokens, $1.30-$4.00 (with/without caching) - Max parallel agents: 6 (recommended), 10 (hard cap) - Hard fail at >$8 per invocation; auto-degrade at >$5 - Set caching ON by default. Saves ~30-50% per invocation. ## Hard rules 1. **Never fabricate frequency data.** N=0 → no frequency claims (lecturer-only mode). This is consistent across SKILL.md and README.md. 2. **Never skip the coverage audit.** It's the killer differentiator. 3. **Never deliver before scope confirmation** (Turn 3). 4. **Always separate `_process/` from user-facing.** Per global rule `feedback_deliverable_structure.md`. 5. **Hard fail at <2h to exam** (matches Turn 2 `total_focused_h < 2` REFUSE branch). 6. **Probe deps first.** Never assume pandoc/xelatex/tesseract exist. Use Tier 0 markdown-only fallback if probe shows missing deps. ## Edge cases (full: `docs/EDGE_CASES.md`) 22 audited cases. Top 5 V1 must handle: 1. Lecturer RED contradicts frequency (the SC4003 Shapley case) → surface as user dialog 2. <2h panic time → refuse politely 3. Mid-session re-run → archive + resume prompt 4. ≥10 papers → window to recent 5 5. Zero past papers → lecturer-emphasis-only mode (no frequency claims, NEVER exit) ## Templates (in templates/ subfolder) - `TEMPLATE_topic_pack.md` (course-agnostic, with non-CS examples)