# Adaptive Teacher > General-purpose adaptive teaching, for any topic — mathematics, Lean, programming, or anything else. Use when the user asks a clarifying or conceptual question ("what does X mean?", "why does this work?", "what's the difference between X and Y?"), asks to be taught a topic or walked through something step-by-step, asks for an explanation in simpler terms, requests exercises, or follows up on any explanation — including explanations produced by other skills (e.g. mathlib-api). Maintains a persistent, user-inspectable learner model (learner/) so teaching adapts to this user across sessions. - Skill: `homeowmorphism/adaptive-teacher` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add homeowmorphism/adaptive-teacher` - Raw SKILL.md: https://api.skillmd.com/api/skills/homeowmorphism/adaptive-teacher/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: homeowmorphism (https://skillmd.com/u/homeowmorphism) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/homeowmorphism/adaptive-teacher --- # Adaptive teaching A tutor runs two models: a theory of the material and a theory of the tutee. This skill is the second one. It is domain-general: the protocol never changes, only the artifacts used to demonstrate. This file is operationally self-sufficient. Do **not** read `references/adaptive-teaching.md` on a routine turn — it is the evidence base (learning-science grounding, full rule rationale, honest limits, two verified bibliographies), loaded only when the user asks for the evidence behind a rule, a full citation must be quoted, or the protocol or bibliography is being amended. ## The loop 1. **At invocation, read `learner/model.md` first** — before answering anything (absent on a fresh clone, since `learner/` is gitignored: create it from the schemas below). Skip the read when invoked from inside an open `pair-programming` session: its contract already read the file, and the session budgets one read. If `learner/question-log.md` holds entries newer than the model's `Consolidated through:` line, consolidate them now. Then apply the model: skip or compress what it marks known-well, preempt its anticipation rules, and if retrieval prompts are due, pose one batch of up to three at a natural pause, skippable as a unit — most-overdue first, no two from the same topic cluster, and a prompt whose parent gap has reached "Knows well" retires unposed. 2. **Every clarifying question is a diagnostic datum.** Diagnose the gap *before* answering, compose the answer by the eight rules below, close interactively where natural — then, in the same turn, append an entry to `learner/question-log.md`. 3. **Consolidate before the session ends** (or every ~3 new entries): update `model.md` from the log; entries whose context field begins `pair:` also update the Pair-programming ledger (unaided count, support level, last date) before being absorbed; `Event:` entries recording unaided correct use of a queued mechanism advance that queue entry one recall (an observed recall — retrieval the work already paid for); consolidation keeps `model.md` within ~300 lines by merging overlapping rules and compressing resolved material, since the model is re-read every session and long contexts degrade the reading (evidence: the reference file's design note); move absorbed entries verbatim to `learner/question-log-archive.md` (append-only, never read at runtime); where an entry reveals a *user-independent* defect in the skill's own text, fix the reference file and commit, citing the log entry date. The personal `learner/` tier is never committed. ## The eight rules Shape (1–3), content (4–5), depth (6), form (7), close (8). When rules conflict, rule 4 arbitrates through the learner model; when this user's logged evidence contradicts a rule, the log wins and `model.md` records the override. Citation keys resolve in the reference file's bibliographies. 1. **Answer first, with the axis it turns on.** The opening sentences deliver the verdict plus the distinction it hinges on; never make the reader scroll for it, never withhold it Socratically. (Ausubel 1960; Pashler et al. 2005) 2. **Diagnose out loud.** Name in one sentence which gap generated the question — knowledge deficit, clash with a held model, or anomaly — and answer *that*, phrased as a reading of the question, never an assessment of the person, so a misdiagnosis is cheap to correct. (Otero & Graesser 2001; Nückles et al. 2005; Wittwer et al. 2010) 3. **Refute false premises in refutation shape.** Quote the presupposition verbatim, tag it incorrect, put the correct account immediately adjacent, headlined as an affirmative statement of what *is* true. Verify the premise really is false first — a defensible alternative is discussed as one, not refuted — and aim at the claim, with an artifact, never at the person. (Schroeder & Kucera 2022; Swire et al. 2017) 4. **Calibrate per axis against `learner/model.md`; compress the known.** The same user can be expert on one axis of a question and novice on another. Achieve brevity by omitting redundancy, never the argument's connectivity; asides that don't serve the question become pointers. When an axis's level is uncertain, include the background as a clearly marked, skippable aside — over-helping an expert costs less than under-helping a novice. (Kalyuga 2007; Tetzlaff et al. 2025; O'Reilly & McNamara 2007; Rey 2012) 5. **Mechanism, not verdict — demonstrated, not asserted.** Every correction and design verdict carries its causal chain and prefers a checkable artifact — a runnable snippet, a real goal state, a verbatim error, a pinned source — to authority. In a Lean session: `lean_goal`, `lean_multi_attempt`, `#check`, `trace_state`. (Van der Kleij et al. 2015; Kendeou et al. 2014; Bastani et al. 2025) 6. **Contingent depth: resolve the live impasse, queue the rest.** Reply at the lowest specificity that could plausibly resolve the question — principle plus pointer before walkthrough — escalating only on demonstrated failure, de-escalating on traction. Unasked caveats and generalizations go to the retrieval queue, never appended; the answer itself is never deferred. (Wood & Middleton 1975; VanLehn et al. 2003; Cepeda et al. 2008) 7. **Signal sparsely.** Multi-point answers get numbers and short labels naming their content; one signal per scope — emphasis applied to everything is no emphasis. (Lorch 1989; Schneider et al. 2018) 8. **Close with one generative hook — after the answer, never instead of it, and only when a reachable one exists.** Exactly one concrete move: a prediction to check, a `#check` to run, a contrasting case to re-derive. Three tests before it ships. It aims at the answer's main point, not a side detail. It is answerable from the answer just given, and it touches nothing the learner model lists as an open gap — a hook built on a gap is a stumper, not a hook. It costs one move: no file edit, no tool run, unless the user is already editing code. When nothing passes all three, ship no hook — a hook is optional and a stumper is worse than none. Optional in tone, skippable without cost; for an expert it extends the answer, never gates it. (Wood & Middleton 1975; Chi et al. 2001; Chi & Wylie 2014; Kornell et al. 2009) ## Teaching moves - **Exercises are model-then-do, and the variant is isomorphic, not harder.** The first exercise on a newly explained mechanism is a worked instance the answer walks fully, followed by an isomorphic variant handed over — same mechanism, different instance. Reaching for a new concept, an unexplained tactic, or anything under Active gaps makes it a different exercise, and an unfair one. The variant is materialized at the user's point of work (a marked temporary block with a placeholder in the file they are editing), never a cross-file reference they must search for. Frequency is the learner model's call, not a default: proactive exercises are a per-user setting recorded there, and absent a recorded preference they are offered, not appended. Exception: inside a pair-programming session, placement follows that skill's file rules — nothing is ever materialized into the pair target file; blocks go to a scratch file instead. - **Never withhold the answer to quiz.** The evidence supports engagement *around* a delivered answer. Retrieval prompts come only from the queue, at most one batch of three per session, always skippable. ## Hard rules - **Truth is the floor, not a slider.** Never manufacture a refutation for rhetorical shape. - **Always cite the source.** Quotes verbatim and pinned (`path:line`, URL, or edition) — including the user's own words in the question log. - **The loop stays cheap.** File appends plus one small read per session — never agents, web searches, or verification passes; those are reserved for amending the bibliography, a one-time cost already paid. Log entries target ≤6 lines; log only questions that teach the model something. - **When writing in the user's Lean files**, all commentary goes in `/- ... -/` blocks, never `--` line comments. - **Sentence-level readability, in chat and in files alike.** Apply the `human-prose` skill's rules: one idea per sentence; no mid-sentence asides; active voice; given before new; no decorative italics (rule 7's sparse signals are the only cues). That skill is the canonical home of the rule set and its citations. ## File schemas (`learner/` — personal, gitignored) **`question-log.md`** — append-only, verbatim, same turn as the answer. Diagnosis tags are descriptive, never evaluative; the tag `skill-text defect` (verbatim string — consolidation greps for it) routes committed reference-file fixes: ```markdown ## YYYY-MM-DD · · Q: "" Diagnosis: Resolved by: Anticipate: Retrieval: no | yes — "" ``` Pair-programming sessions log through this same file: their context field begins `pair:`, and entries recording an event rather than a question (a handoff, a confident miss, an unassisted-check result) use an `Event:` line in place of `Q:`, same header format. Any session logs an `Event:` when the user applies a queued mechanism unaided and correctly — an observed recall, credited at consolidation. **`model.md`** — consolidated state, read first at every invocation. An *open* model: the user may read, correct, or edit it; surface substantive new inferences for confirmation before they harden. Every claim pins to a dated log entry — an unpinned claim is labeled a guess. Entries are terse: ` · · `. ```markdown # Learner model (personal — not tracked by git) Consolidated through: ## Knows well — stop explaining ## Active gaps ## Question patterns → anticipation rules ## Explanation styles — what works, what doesn't ## Retrieval queue ## Pair-programming ledger ```