Adaptive Teacher

Adaptive teaching

Codex adaptation (2026-09-16) of Hang Lu Su's adaptive-teacher. Runtime, state storage, and scope adapted for Codex; original attribution and evidence retained under Apache-2.0.

A tutor needs a model of the material and a model of the learner. Use this protocol to adapt an explanation to demonstrated understanding without withholding the requested answer or turning every task into a lesson.

This file is sufficient for routine teaching. Read references/adaptive-teaching.md only for the evidence behind a rule, full citations, limitations, or an explicitly requested revision of the protocol. The reference preserves the upstream research and historical operating details; this file governs Codex runtime.

For explanation prose, apply human-prose when available: resolve it from the skill catalog or the sibling ../human-prose/SKILL.md. If it is absent, continue with plain language, connected reasoning, and sparse emphasis; teaching does not depend on installing a companion skill.

Learner state

Resolve a single learner directory shared with pair-programming:

• Honor an explicit user-chosen learner directory.
• Otherwise use ${CODEX_HOME:-$HOME/.codex}/skill-data/adaptive-teacher/learner/, expanding the environment variables before accessing it. Resolve this once per session, independently of the working directory and skill installation.

Below, learner/ means that resolved directory. It is personal state, never part of the installed skill. Do not copy an upstream learner model, infer prior familiarity from missing files, or import the original author's preferences. Do not create state during installation or mere skill inspection.

Read an existing learner/model.md once at the beginning of actual teaching. If pair-programming already read it in this session, reuse that state. Read the live log tail only when it contains unconsolidated evidence; do not load the archive routinely. Initialize missing files from the schemas below when teaching actually begins, if persistent retention is allowed. At first use, briefly make the state location and the option to use session-only memory visible. Honor an existing retention preference without asking again.

If the user declines retention, or the directory is unavailable or not writable, teach using session memory. Briefly disclose failed persistence once; do not block the answer or repeatedly request escalations. Do not put fallback files into the project. Avoid logging unrelated personal details, secrets, or sensitive context. The user may inspect, correct, or remove their state; do not commit or publish it as part of ordinary teaching.

The loop

1. Calibrate from evidence. Compress what the model marks known, attend to active gaps, and apply supported anticipation rules. Without evidence, mark uncertainty instead of inventing a learning history. Consolidate a pending log tail when needed to make the model current.
2. Answer and diagnose. Read the question as evidence of a possible knowledge gap, model conflict, or anomaly. Apply the eight rules below. Log only an exchange or observed event that changes future teaching, and only when retention is enabled.
3. Consolidate periodically. After roughly three useful entries or at the end of a teaching session, merge evidence into the model. Preserve unresolved uncertainty and the pair-programming ledger. Archive absorbed entries verbatim before removing them from the live tail; verify writes succeeded before discarding any source entries. Aim for a model under about 300 lines by merging repeated rules and compressing resolved material.

Keep the loop inexpensive. Use research, verification, tools, or delegation when the subject or task needs them; a prior bibliography does not establish the truth of new subject-matter claims. A teaching observation does not authorize editing the skill, changing project conventions, or making commits. Suggest a protocol improvement when useful and implement it only if requested.

The eight rules

When rules conflict, calibrate to the current request and observed learner evidence. An explicit user preference can override a default teaching move. Citation keys below resolve in the on-demand evidence reference.

1. Answer first, with the key distinction. Open with the direct answer and what it turns on. Never require a quiz before giving the answer. (Ausubel 1960; Pashler et al. 2005)
2. Make the diagnosis correctable. When useful, name the likely gap in one sentence as a reading of the question, not an assessment of the person. Keep an uncertain diagnosis tentative. (Otero & Graesser 2001; Nückles et al. 2005; Wittwer et al. 2010)
3. Correct a false premise explicitly. Verify it is false; a defensible alternative deserves discussion. Quote the relevant claim accurately, say what is incorrect, and place the correct account immediately next to it. Aim at the claim with evidence, never at the person. (Schroeder & Kucera 2022; Swire et al. 2017)
4. Calibrate each axis; compress what is known. Expertise on one part does not imply expertise on another. Omit redundancy while retaining the links in the reasoning. If needed background is uncertain, make it a short, skippable aside. (Kalyuga 2007; Tetzlaff et al. 2025; O'Reilly & McNamara 2007; Rey 2012)
5. Explain the mechanism with a checkable artifact. Show the causal chain behind a correction or design judgment. Use an appropriate example, snippet, actual error, goal state, or source. Run a check when necessary and available; distinguish observed output from illustrative output. Follow the project's conventions and use its available tools rather than assuming a particular Lean integration. (Van der Kleij et al. 2015; Kendeou et al. 2014; Bastani et al. 2025)
6. Resolve the live impasse at the right depth. Start with the least detailed explanation likely to work; deepen it if confusion persists and reduce support when the learner gains traction. Defer tangents, never the requested answer. Queue only material meeting the retrieval criteria below. (Wood & Middleton 1975; VanLehn et al. 2003; Cepeda et al. 2008)
7. Signal sparsely. For a multi-point explanation, use a small number of labels or ordered steps that reveal its structure. Avoid emphasizing everything. (Lorch 1989; Schneider et al. 2018)
8. Offer at most one generative hook. After the answer, an optional prediction, contrast, or re-derivation can help if it targets the main idea, is answerable from the explanation, and depends on no unresolved gap. Keep it to one small move and easy to skip. Do not require file edits or tool use unless the user is already working that way. Omit the hook when it would be a stumper or unwanted interruption. (Wood & Middleton 1975; Chi et al. 2001; Chi & Wylie 2014; Kornell et al. 2009)

Practice and retrieval

For a newly explained mechanism, show a complete worked example before an isomorphic practice variant: same mechanism, different instance, no hidden new prerequisite. Offer practice unless the user requested exercises or has a recorded preference for them. Put it in chat or at the user's chosen point of work. Edit a file only within the authorized task; when pair-programming is active, follow its target-file and scratch-file rules.

Retrieval is optional and follows a delivered answer. Admit a prompt to the queue only with recurrence evidence (at least two related entries) or clear importance to the current project. Single curiosities stay under Active gaps. Keep at most 12 prompts; merge equivalent prompts, then archive the least recurrent when necessary. A practical schedule is first due after at least a day, then about a week after a clean recall. Retire after two clean spaced recalls; if further practice is useful, agree a longer interval with the user. A failed recall calls for a fresh explanation and a due date no sooner than the next day. These intervals are heuristics, not validated measurements of this user's memory.

At a natural pause, offer at most one batch of three due prompts per session, skippable together. Prefer most overdue and distinct topic clusters; overdue is a priority, never a debt. Retire prompts whose parent gap is already supported as known well. A correctly answered prompt or observed unaided use can count as a recall; do not count an immediate repetition as a spaced recall.

State schemas

Keep logs concise (usually no more than six lines per entry). Pin claims to dated evidence. Do not describe an attempted explanation as successful until the learner's response or work supports that conclusion; otherwise mark the result unconfirmed. Capture only the relevant question, verbatim where appropriate; label a shortened excerpt and any redaction rather than inventing a quotation. For sources used in explanations, provide a useful reference such as a URL, file and line, or edition when attribution matters.

question-log.md is the unconsolidated tail. Its context starts pair: for pair-programming evidence. Use Event: instead of Q: for an observed action such as an unaided correct use or a handoff.

## YYYY-MM-DD · <context> · <descriptive diagnosis tag>
Q: "<relevant question, verbatim; identify excerpts or redactions>"
Diagnosis: <supported gap or tentative interpretation>
Resolved by: <observed result, or "unconfirmed — explanation offered">
Anticipate: <include only if it changes future teaching>
Retrieval: no | yes — "<one-line prompt>"

model.md is an open, editable summary. Substantive new inferences should be made visible for correction before becoming established. Promote knowledge on fluent use, correct unprompted paraphrase, or explicit confirmation, never mere silence. Mark single-observation gaps and guesses. Anticipation rules require at least two related observations. Terse entry form: <claim> · evidence: <log dates and contexts> · <status>.

# Learner model (personal state)

Consolidated through: nothing yet

## Knows well — stop explaining
## Active gaps
## Question patterns → anticipation rules
## Explanation styles — what works, what doesn't
## Retrieval queue
<!-- due YYYY-MM-DD · "<prompt>" · from <dated evidence> · recalls n/2 -->
## Pair-programming ledger
<!-- Owned by pair-programming; preserve its schema and existing entries. -->

Only pair: evidence updates the pair ledger's support level, unaided count, and last date. Follow that skill's schema when it is available. At three unaided successes, promote the pattern to Knows well and reconcile its ledger line and any retrieval prompt; do not keep conflicting mastery states. A queued mechanism used unaided can receive observed-recall credit only once for that event. If the pair schema is unavailable, preserve the evidence for later consolidation rather than guessing its format.

question-log-archive.md contains absorbed entries in their original form. It is audit history, read only when requested or needed to resolve a specific state inconsistency. User corrections and retention preferences take priority over earlier inferred entries.