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:

## YYYY-MM-DD · <phase or context> · <diagnosis tag>
Q: "<the question, verbatim>"
Diagnosis: <which gap the question reveals>
Resolved by: <what actually worked, not what was tried first>
Anticipate: <omit unless it changes future behavior>
Retrieval: no | yes — "<one-line prompt to re-ask later>"

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: <claim> · <evidence: log date(s)> · <status>.

# Learner model (personal — not tracked by git)

Consolidated through: <date · context of last absorbed entry, or "nothing yet">

## Knows well — stop explaining
<!-- promote only on fluent use, correct unprompted paraphrase, or explicit
     confirmation — never a single non-question -->
## Active gaps
<!-- single-datum gaps marked as such, never hardened -->
## Question patterns → anticipation rules
<!-- promoted after ≥2 related log entries; each names where to preempt -->
## Explanation styles — what works, what doesn't
## Retrieval queue
<!-- `due YYYY-MM-DD · "<prompt>" · from <log date> · recalls n/2` —
     spacing: ≥1 day, then ~a week, then ~a month; retire after two clean
     spaced recalls; failed recall → re-explain, reset to due-tomorrow.
     A clean recall is explicit (posed prompt answered) or observed (an
     Event: logging unaided correct use in real work); both count the
     same, and observed ones are free.
     Per session: ONE batch of ≤3 due prompts at one natural pause,
     skippable as a unit; most-overdue first (cheap proxy for lowest
     retrievability); no two prompts from the same topic cluster
     (interleave confusables, don't block them); a prompt whose parent
     gap reached "Knows well" retires unposed. Overdue is a priority key,
     never a debt — nothing stacks.
     Admission: recurrence evidence (≥2 log entries) or current-project
     critical path; single-datum curiosities stay under Active gaps.
     Hard cap 12 — on overflow, merge isomorphic prompts, then move the
     lowest-recurrence entries to the archive under a dated heading. -->
## Pair-programming ledger
<!-- owned by the pair-programming skill; schema in its SKILL.md.
     Consolidation preserves this section; only pair-tagged evidence
     updates it. Promotion at 3 unaided moves the pattern to "Knows
     well" and deletes its ledger line, so a pattern never carries both
     a ledger count and a queue entry without reconciliation. -->