exam-drill

---
name: exam-drill
description: Use when the user wants exam-focused drilling from the course's analyzed material. Generates twin variants of known problems (`/twin`), runs strategy-level blind drills on known problems (`/blind`), creates integration problems chaining multiple patterns (`/chain`), surfaces pattern cards (`/pattern`), and shows coverage/exam-tier maps (`/hwmap`). Reads from `course-index/patterns.md`, `course-index/coverage.md`, and `converted/solutions/*.md`. Works for any math/physics course that has been ingested and analyzed.
---

# Exam Drill

## Workflow philosophy (critical — do not break)

**The user does not type math into the CLI — it is too slow.** All interactions obey:

1. **Generation side (Claude → file).** Problems, variants, and clean reference derivations are written as markdown files to `quizzes/`, `twins/`, `chain/`, `derivations/`. The user views them; no math dialogue in the terminal.

2. **Answer side (user → PDF).** The user solves on paper, scans as PDF, uploads to `answers/<name>.pdf`. The `answer-processing` skill (auto-loaded by `/grade`) converts the PDF to markdown and grades.

3. **Strategy checks (when user is online)** — when a command asks the user to verify understanding without producing a full written solution, it asks only for the *strategy* in 3–5 lines of prose (written in `INTERFACE_LANG` from `.course-meta`, default `en`): which pattern(s), which variables are fixed/expanded, what form the answer takes. Strategy matching is stronger evidence of mastery than line-by-line algebra.

## Drill targeting philosophy (critical — do not break)

**HW density = exam probability.** The professor has already told you, through HW, where the exam points live. Every drill command **must bias toward HW-emphasized sections** (🔥🔥 Exam-primary > 🔥 Exam-likely > 🟡 Exam-possible). Sections with no HW (⚪ Low-risk) are **not** "blind spots waiting to bite" — they are the professor's signal of what is off the exam. Do not treat low-HW sections as high-risk.

Concretely:
- `/twin`, `/blind` default to the highest-HW-density problems when the user doesn't specify one.
- `/chain` composes patterns drawn from Exam-primary sections; avoid pulling patterns from ⚪ sections unless the user explicitly asks.
- `/mock` problem weighting follows HW density (see `commands/mock.md`).
- `/quiz all` samples ≥70% from 🔥🔥, ~25% from 🔥, ≤5% from 🟡, 0% from ⚪.
- If the user requests a ⚪ section drill, comply once but warn that exam probability is low.

## Prerequisites

This skill assumes `/ingest` and `/analyze` have been run. If `course-index/patterns.md` or `course-index/coverage.md` don't exist, tell the user to run those first.

## Files read

- `course-index/patterns.md` — recognition cards P1, P2, ...
- `course-index/coverage.md` — HW↔§ map, 🔥 exam tiers + ⚠weak flags
- `course-index/summary.md` — topic tree
- `converted/homework/*.md` — original HW problems
- `converted/solutions/*.md` — HW solutions (ground truth for grading)
- `errors/log.md` — user's error history (append-only)

## Files written

**`<ts>` is always `date +%Y%m%d_%H%M%S`** (e.g. `20260611_213627`) — one canonical
timestamp format for every drill artifact (`/quiz`, `/twin`, `/chain`, `/mock`).
Use underscores, not a `-` between date and time, and do not improvise a per-run
format. The stem you save (`<id>_<ts>_sol.md`) must be the exact `<ts>` you print
in the upload instruction (`answers/…_<ts>.pdf`) so `/grade` resolves it and the
course folder doesn't accumulate mixed-format filenames. (Generate it once with
`date +%Y%m%d_%H%M%S` and reuse that string for both the saved files and the
printed upload name.)

- `quizzes/<topic>_<ts>.md` — problem statements (answers in `_answers.md` sibling)
- `twins/<origin>_<ts>.md` — variant problems
- `chain/<ts>.md` — integration problems
- `derivations/<topic>.md` — clean reference derivations (post-success)
- `errors/log.md` — append error entries

## Command patterns

### `/twin <problem-id>`

1. Locate `<problem-id>` in `converted/homework/` and `converted/solutions/`.
2. Identify patterns used via `course-index/patterns.md`.
3. Apply twin-recipe.md rules: hold pattern and topic invariant; vary system, numbers, direction, names.
4. Save problem to `twins/<id>_<ts>.md` and solution to `twins/<id>_<ts>_sol.md`. Do not reveal solution unless user either (a) uploads their answer PDF, or (b) describes a correct strategy.

### `/blind <problem-id>`

1. Present the problem verbatim from `converted/homework/`.
2. Ask for strategy (3–5 lines, in $INTERFACE_LANG):
   - which pattern(s) from `course-index/patterns.md`
   - what variables are fixed vs. varied
   - expected form of the final answer
3. Compare against `converted/solutions/`. Three checks: pattern / variable-choice / end-form.
4. On success, copy the relevant solution section into `derivations/<stem>-<n>.md`. On failure, flag the specific axis and log to `errors/log.md`.

### `/chain <N>`

1. Pick N patterns from different source problems (per `course-index/coverage.md`).
2. Design a problem that requires composing them sequentially in parts (a), (b), (c).
3. Bias toward user's weak zone (sections flagged `⚠weak` in `course-index/coverage.md`, or the latest weakmap's top entries).
4. Save problem and solution; prompt for part-by-part strategy or PDF upload.

### `/pattern [§ or keyword or "all"]`

Read-only. Filter `course-index/patterns.md` by the query and return compact pattern cards.

### `/hwmap [§ | "hot" | "all"]`

Read-only. Project `course-index/coverage.md` by the query. `hot` ranks 🔥🔥/🔥 sections by HW density with their HW drill anchors and a per-§ recommendation (`blind` is accepted only as a legacy alias for `hot` — there is no blind-spot listing mode; ⚪ no-HW sections are low-risk by design).

## Twin recipe (invariance rules)

**Hold invariant:**
- The pattern(s) required — a twin that uses a different method is not a twin, it's a new problem.
- The number of reasoning steps (±1).
- The course topic/section being tested.
- The difficulty tier (recall / calculation / derivation / analysis).

**Vary:**
- Numerical values.
- Variable names.
- System/model specification (if course admits multiple — ideal gas → vdW, ODE → PDE of same order, matrix 3×3 → 4×4).
- Direction of the ask: "show X = Y" ↔ "given X = Y, verify Z" ↔ "compute X".

**Quality check before presenting:**
1. The target pattern is clearly required (not avoidable by a shortcut).
2. The answer differs from the original (if it matches, it's not a twin).
3. No filename or wording directly references the original problem ID.
4. Final answer exists and is not pathological.

## Error logging schema

When any drill reveals an error, write to `errors/log.md` **through the
deterministic writer** — one call per graded source, entries as stdin:

```bash
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/log_tool.py" append --source=<source> <<'YAML'
- problem_id: <HW#-P#, twin-id, or chain-ts>
  pattern: <Pk from patterns.md>
  error_type: pattern-missed | wrong-variable | wrong-end-form | algebraic | sign | definition
  summary: "<one-line description>"
  source: <answers/converted/<name>.md | blind/<id> | chain/<ts>>
  date: <ISO8601>
YAML
```

This is the **same canonical schema** as `skills/answer-processing/SKILL.md` Step 6 — keep every key, including `source:` (the statusline's mock-phase detection regexes on it, and it doubles as the `--source=` idempotence key: re-grading a source replaces its entries instead of piling up duplicates). The tool schema-validates and writes atomically; never hand-edit the log's appended entries. `/weakmap` (top-level command) consumes this log; this skill just produces entries.

## Cross-skill coordination

- `/grade` → loads `answer-processing` skill (PDF → MD → compare with `converted/solutions/`).
- `/ingest` or `/analyze` → loads `course-builder` skill.
- Any PDF read/write → loads `pdf` skill.
- All drill outputs (twins/, chain/, quizzes/) use plain markdown — no PDF creation inside drill commands. The user uploads answer PDFs; Claude doesn't make PDFs during drilling.

## Prose conventions

- Explanations in `INTERFACE_LANG` (en or ko) from `.course-meta`. Default `en` if the field is absent.
- Math in LaTeX (`$...$` inline, `$$...$$` display).
- Pattern IDs stay Latin (P1, P2, ...) regardless of language.
- Section IDs follow the course's convention from `course-index/summary.md` (§, Ch., Ch 3.1, etc.) regardless of language.
- File paths, slash command names, YAML keys, and section anchors downstream tools regex on (`## One-line verdict`, `## Page N`, `# Vision-OCR transcription`) stay in English regardless of language.

• SKILL.md 9 KB
• twin-recipe.md 4 KB