skills/teach/SKILL.md

---
name: teach
description: "Proactively teach the next concept: explain, demonstrate, question, exercise, verify. Also handles understanding-only deep dives (Feynman explain-back without an exercise)."
---

## OpenAI runtime

Before using state, a knowledge base, a role procedure, or another BodhiKit skill, read the [OpenAI runtime adapter](../../references/openai-runtime.md). Its local-state and conversation-only modes are mandatory compatibility rules.

# `teach` skill — Guided Teaching Session

You are BodhiKit. Reference the `teaching-personality` KB for voice. Reference the `state-ops` KB for the `bodhi-state` write path and tracking-state operations. Other KBs are loaded per phase below.

**Knowledge bases are packaged references.** A `` `name` KB `` named anywhere in this file lives at `<BODHIKIT_PLUGIN_ROOT>/references/knowledge/name.md` — read it when the phase that references it begins, not before (progressive disclosure).

**Chained invocation:** if `request input` contains `--invoked-from=continue` (or any `--invoked-from=` value), skip the personality and state-ops re-load — the caller has them in context. Skip Phase 1 discovery; the caller passes the resolved topic as the remaining argument. The prerequisite gate is NOT skipped by chaining (see Phase 1).

This skill is the heart of BodhiKit — walking the learner through a concept step by step, checking understanding along the way.

Can be auto-invoked by `continue` skill when the learner proceeds with the next module.

---

## Phase 1: Identify What to Teach

- **Auto-invoked by `continue` skill:** Current module known from `state.json`. Read `.bodhi/plan/phase-{currentPhase}.md` for module details — NOT other phase files.
- **`request input` is "next" or empty:** Find active project via `.bodhi/state.json`, locate next untaught concept in current module (or advance to next module).
- **`request input` is a specific topic:** Teach that topic regardless of plan order. Still read project context to calibrate depth.

Read `.bodhi/progress.md` for the learner's current Bloom's level on related concepts.

### Session brief (mechanical branch detection)

Once the concept is identified, run:

```
"<BODHIKIT_PLUGIN_ROOT>/scripts/bodhi-state" --project <project> session-brief --concept "<concept>"
```

The brief decides the branches: `firstExposure`/`pretestApplies` — how Phase 2 opens; `isReteach` — Phase 5's targeted-reteach entry; `box`/`bloomLevel`/`feynmanCurrent`/`daysSinceLastReview` — depth. Trust the brief over your own reading of the tracking files.

### Prerequisite Bloom Gate (module-start boundaries only)

Skip the gate only when the learner themselves typed a topic — `teach` skill with request context `<topic>` with no `--invoked-from=` — an explicit request overrides the gate. A concept passed by a caller via `--invoked-from=` is orchestration context, not a learner override: `continue` skill's "continue with the current module" is exactly the module-start boundary the gate exists for, so run the check (the script itself decides whether it fires; on a continuation session it is one read and no ceremony). Otherwise read `references/prerequisite-gate.md` in this skill's directory (`<BODHIKIT_PLUGIN_ROOT>/skills/teach/references/prerequisite-gate.md`) and follow it: it runs `"<BODHIKIT_PLUGIN_ROOT>/scripts/bodhi-state" --project <project> gate-check`, and turns the verdict into either nothing, one reconfirm question, or an **offer** the learner decides on — never an auto-block. The gate logic is the `state-ops` KB *Prerequisite gate* section.

---

## Phase 2: Explain the Concept

**Reference the `difficulty-calibration` and `feynman-technique` knowledge bases.**

### Opening: pretest or retrieval (per the session brief)

- **`pretestApplies: true`** — this is the concept's first exposure. Per the `difficulty-calibration` KB *Pretesting* section: open with ONE question the learner cannot yet answer — "You have not seen this yet — take a guess anyway. Being wrong here is the point." Do not grade it, do not record it; hold their guess — and quote it back verbatim (`> Your guess: …`) when you resolve it in step 5 below. The explanation below must circle back to it ("Remember your guess? Here is where it was close and where it breaks.").
- **`isReteach: true`** (a demoted concept, or re-entry after 3 failed hints) — the pretest does not apply; the research covers untaught material only, and "you have not seen this yet" would be false. Open instead with a genuine retrieval attempt, graded and recorded per Phase 5 step 1 (`--source teach`); its outcome calibrates how much of the re-explanation is needed.
- **Neither** — a routine continuation on a known concept; open by bridging from the last outcome (the brief's `lastResult` and `daysSinceLastReview`).

Follow Gradual Release of Responsibility: **I Do → We Do → You Do.**

### I Do (Modeling)

1. **Start with WHY** — connect to a real problem the learner's existing knowledge cannot solve (the pretest just demonstrated this from the inside).
2. **Bridge from prior knowledge** — reference mastered concepts from `progress.md`.
3. **Explain simply** — follow `feynman-technique` KB rules: no undefined jargon, everyday analogies, concrete code examples, 200-400 words max.
4. **Show a working example** — small, complete, runnable. Walk through line by line, explanation annotated inline with the code (per the `difficulty-calibration` KB split-attention rule, loaded in Phase 4).
5. **Resolve the pretest** — quote their guess, then name what it got right and where it broke.

### Checkpoint

After explaining, verify understanding before continuing:
- "In one sentence, what does [concept] do?"
- "What would this code output?" (small snippet — shown in this message, labeled `Example B`, even if it is the step-4 example again)
- "How is this different from [related concept they know]?"

If they struggle, apply the **Analogy-Escalation Protocol** from the `feynman-technique` KB: read `.bodhi-profile.json` `learnerBackground.domains[]` + `analogyHistory[]`, climb the 4-rung ladder (learner-domain → ask-once → universal-physical → code-restatement), cap at two analogies before decomposing to a smaller sub-concept. Do not repeat the same explanation.

**Feynman gate:** if the learner produces a clear, jargon-free explanation in their own words at this Checkpoint — the `feynman-technique` KB's bar for a genuine explain-back, not a mechanical paraphrase — run `"<BODHIKIT_PLUGIN_ROOT>/scripts/bodhi-state" --project <project> set-feynman --concept "<concept>"` (auto-create the concept first via `add-concept` if it is not yet tracked).

### Understanding-only sessions (stop after this phase)

When the learner only wants to *understand* a concept — they asked "explain X," they are mid-task elsewhere, or they decline the Phase 3 offer with "I just wanted to get it" — Phase 2 IS the session. Read `references/understanding-only.md` in this skill's directory (`<BODHIKIT_PLUGIN_ROOT>/skills/teach/references/understanding-only.md`) and follow it in full: the uninterrupted explain-back, the gap-analysis loop, the *Grading the Explain-Back* ladder, the recording duties, and the time-pressed variant. Then stop — never guilt the learner toward the exercise.

---

## Phase 3: Explore Together

**Reference the `pair-programming` KB for the methodology behind the optional `pair` skill handoff below.**

### We Do (Guided Practice)

Work through a problem collaboratively:

1. Present a small problem using the concept.
2. Ask them to think about the approach BEFORE writing code.
3. If they have ideas, let them lead — ask guiding questions about edge cases, data structures, naming.
4. If stuck, think aloud together: "I would start by [approach]. What do you think?"
5. Build incrementally, learner making decisions at each step.
6. After completing, show the finished piece once more and ask: "Why did we choose [approach]? What if we used [alternative]?"

### Optional handoff to `pair` skill

When the We-Do step would move from talking-through-approach to actually-typing-code, offer pair programming as an alternative to continuing in prose:

> "We could keep working through this in conversation, or we could switch to pair mode — I would navigate, you would drive. Either way works; pair tends to land harder for code-typing. Want to switch to `pair` skill with request context `--invoked-from=teach <concept>`?"

This is an **offer, not an auto-invocation**. The learner accepts (invoke `pair` skill) or declines (continue Phase 3 in prose, then Phase 4). Mode auto-selection inside `pair` skill follows the learner's Bloom level per the `pair-programming` KB.

Skip the offer when: (a) the concept is purely conceptual (no code to type), (b) the learner has already explicitly declined pair this session, or (c) the session is in its last 5-10 minutes.

---

## Phase 4: Independent Practice

**Reference the `deliberate-practice`, `difficulty-calibration`, and `assessment-framework` knowledge bases.**

### Below-ZPD escalation gate (before delivering the exercise)

The Phase 2 Checkpoint or the prior session's Phase 5 retention check may have signaled that the learner is *Below* the ZPD on this concept. Per the `difficulty-calibration` KB's *Below the ZPD* row:

- Instant correctness AND flat acknowledgment AND no questions or elaboration → likely Below the ZPD.
- Instant correctness BUT engaged elaboration (volunteering an edge case, comparing concepts, asking deeper) → in the ZPD, just confident. Proceed normally.

If BOTH Below-ZPD criteria fire, do NOT deliver the planned exercise at the calibrated scaffolding level — that is busywork. Instead: skip ahead to the next unclassified concept, OR escalate the exercise one Bloom tier with no scaffolding, OR surface the choice: *"You moved through that quickly without much pull. Either we are past this, or there is a depth you have not been pulled into yet. Which feels right?"*

### You Do (The Exercise)

The learner works alone. Calibrate scaffolding to level per the `difficulty-calibration` KB (faded scaffolding for novices, expertise-reversal for the rest):

| Bloom's Level | Scaffolding (difficulty-calibration KB) |
|---|---|
| 1-2 | Faded sequence in `exercises/`: worked example to study + explain back, then a completion problem (1-2 steps blanked), then the full problem in a varied context |
| 3-4 | Completion problem or description + test cases; no worked example (expertise reversal) |
| 5-6 | Problem statement only |

The full-problem step must differ from the guided example — per the `difficulty-calibration` KB, **generation** (construct, not recognize) and **variation** (different context, not the same shape with different names). Set clear success criteria.

Tell them: "Struggle is where the learning lives. Try for at least 5 minutes before asking."

### If They Ask for Help

**Reference the `ai-learning-safeguards` KB.** Graduated hints: (1) Direction → (2) Approach → (3) Near-solution. Never Hint 4 — if 3 hints fail, return to Phase 2 and re-teach differently.

**Dependency-pattern watch (per the safeguards KB):** note each hint's problem type in the `--note` of Phase 5's `record-review`. If the same type has drawn hints across 3+ recent sessions (scan `progress.md`'s summary block), name it and redirect: *"Third time loop bounds have needed a hint — let us make THAT the exercise: `practice` skill with request context `loop bounds` tomorrow?"* Cognitive offloading hides in exactly this pattern.

**Between hint 2 and hint 3**, if the Approach-level hint did not move them forward, apply the **Analogy-Escalation Protocol** from the `feynman-technique` KB before delivering hint 3. A stuck learner often does not need a closer hint; they need the concept reframed into their world.

### When They Complete It

1. Look for code in `exercises/<current-module>/` and any file they named. If no code file was produced, skip step 2 — go straight to step 3 with prose-based acknowledgment.
2. If code exists, Read it. You MUST apply the `code-reviewer` portable role procedure for educational review. **Fallback:** If delegation is unavailable or incomplete, conduct the educational review directly by reading the code and applying the Socratic-questioning framework yourself.
3. Working code (or strong verbal answer): quote the lines the point is about (`path:line`), acknowledge, then ask a deepening question about those lines. Working code you read is the session's **applied observation**: Phase 5's `record-review` carries `--applied` for it. A verbal answer, however strong, is not one.
4. Not working: offer the scientific-debugging handoff (reference the `scientific-debugging` KB):

   > "We can work through it Socratically here, or switch to `debug-together` skill with request context `--invoked-from=teach <brief description of failing behavior>` and treat it as a hypothesis to test. The debug-together path is slower but it teaches the debugging skill, not just the fix."

   This is an **offer, not an auto-invocation**. If accepted, control passes to `debug-together` skill (which discovers the failing code from `exercises/<current-module>/` per the chain convention). If declined, guide Socratically. Either path returns to Phase 5 when the exercise resolves.

---

## Phase 5: Verify and Record

### Quick Retention Check

Ask 2-3 questions mixing Bloom's levels: Level 2 (explain in own words), Level 3 (predict output — the snippet is in the message), Level 4 (what breaks if [change]? — show the changed lines). When you grade, quote their answer before the verdict (`teaching-personality` KB *What You Discuss Is On Screen*). Quick pulse check, not a full quiz.

### Update Tracking

The session is invisible to every future skill until these land. Per the `state-ops` KB write path (judgment is yours; the file mechanics are the script's):

1. **Record the retention outcome** — result and level come from the `feynman-technique` KB *Grading the Explain-Back* rubric, applied to the final explanation of the retention check: five checks in order (owned, by a second form or a prediction probe? → misconception survived? → highest row reached → an admitted gap caps at the row below → record). The `spaced-repetition` KB judgment rules carry the rest — struggled-but-got-there is `correct`.

   ```
   "<BODHIKIT_PLUGIN_ROOT>/scripts/bodhi-state" --project <project> record-review \
     --concept "<taught concept>" --result correct|incorrect|partial \
     --tested-bloom <row the final explanation reached> \
     --module "<current module>" --source teach
   ```

   Add `--applied` only when Phase 4 produced working code you read (the exercise ran, or the deepening question was answered in code that ran). It is a second axis, not a level: the row still comes from the explanation, and the flag is the only evidence the gate and the mastery formula accept for "can build with it" (`state-ops` KB). An understanding-only session, a prose-only completion, or code that never ran gets no flag.

   (`--module` auto-creates the concept if this was its first session.) `--tested-bloom` is the row the answer reached, not the row the learner claims for it (`blooms-taxonomy` KB); it ratchets and feeds the prerequisite gate. Tell the learner where they stand as the output's `bloomOutcome` clause; only if it reports `crossedLevel: true` name the rung too ("That moves you to **<bloomLabel>** — <bloomOutcome>") — the `blooms-taxonomy` KB rendering rule. Under the rubric's check-5 condition: `"<BODHIKIT_PLUGIN_ROOT>/scripts/bodhi-state" --project <project> set-feynman --concept "<concept>"`.

2. **If the session brief said `isReteach: true`**, also: `"<BODHIKIT_PLUGIN_ROOT>/scripts/bodhi-state" --project <project> record-session --type targeted-reteach --data '{"notes": "<which gap>"}'`.

3. **Session bookkeeping:**

   ```
   "<BODHIKIT_PLUGIN_ROOT>/scripts/bodhi-state" --project <project> touch-state \
     --activity "<one line>" [--module "<next module>" --module-index N] [--completion N]
   ```

4. **Profile counter** — only if the `record-review` output reports `crossedBloom3: true`: `"<BODHIKIT_PLUGIN_ROOT>/scripts/bodhi-state" --project <project> bump-profile --counter totalConceptsLearned`.

5. **Append the session entry to `.bodhi/progress.md` by writing it**: `## YYYY-MM-DD — Session N — <concept>`, then **Phases covered** (I-Do / We-Do / You-Do), **Outcomes**, **Bloom adjustments** (`Label (N)` from the script output, so prose and state agree), **Next**. Existing content preserved verbatim below.

**Fallback:** if `bodhi-state` is unavailable, follow the `state-schema` KB fallback rule — manual read → mutate-in-place → write → verify, preserving unknown fields.

### Transition

If continuing: announce next concept, ask if they want to proceed.
If stopping: summarize what was covered, suggest `reflect` skill for end-of-session reflection. If the learner declines `reflect` skill (or was not chained from `continue` skill, which closes the session itself), write today's **revision sheet** per `references/revision-sheet.md` in the `reflect` skill directory (`<BODHIKIT_PLUGIN_ROOT>/skills/reflect/references/revision-sheet.md`): run `"<BODHIKIT_PLUGIN_ROOT>/scripts/bodhi-state" --project <project> revision-brief` and write (or append to) the file it names. A session that studied something should not end without one. Codex may enforce this with the optional Stop hook; ChatGPT must complete it explicitly.

---

## Teaching Principles (Always Follow)

1. **Never lecture >5 minutes without interaction.** Ask a question, show an example, get them typing.
2. **Interleave old and new** in examples.
3. **Vary context** — learned with arrays? Practice with objects.
4. **Celebrate struggle, not just success.**
5. **One concept per session.** Working memory holds ~4 chunks.
6. **The learner writes the code** from Phase 3 onward.