teach

Purpose

Teach a user interactively across multiple sessions. Not by lecturing, but by coaching through the Knowledge-Skills-Wisdom progression grounded in the user's real goals. Maintains persistent learning state so each session builds on prior understanding.

Use when: user asks to learn across sessions (teach me, study session, help me learn, onboard me to). Skip when: one-off inline question (answer directly); task-context codebase investigation (use the project's own code-exploration tooling); extracting book knowledge to a reference file (/knowledge:book-distill when installed).

Two modes share pedagogy but differ in source material:

• topic. General subject learning. Resources come from external high-trust sources (books, courses, docs, communities).
• codebase. Repo-grounded learning. Resources come from the consuming repo's own code, docs, ADRs, conventions, discovered at teach-time (see "Codebase mode").

Workspace layout (where persistent learning state lives): see "Workspace layout" below. The single source of truth every action resolves paths against. Informed by ZPD/K-S-W pedagogy research.

Workspace layout

Learning state is the user's own study material. User documents, not machine internals. Every workspace lives at <workspace-root>/<project-slug>/<mode>/<topic>/, where <workspace-root> resolves per "Workspace root resolution" below (topic mode defaults to the OS Documents folder's Claude Learning/ home where one is eligible; codebase mode defaults to ${CLAUDE_PLUGIN_DATA}); no root ever pollutes the consuming repo unless the project itself declares one:

<workspace-root>/<project-slug>/<mode>/<topic>/
├── MISSION.md               WHY the user is learning this — goal, success criteria, constraints (workspace-global)
├── GLOSSARY.md              durable terminology SSOT — add only when the user demonstrates understanding (global)
├── RESOURCES.md             curated high-trust sources (knowledge + wisdom communities) (global)
├── NOTES.md                 teaching preferences + working notes — how the user wants to be taught (global)
├── assets/                  shared lesson components — lesson.css + answer-shuffling quiz.js, spliced into HTML lessons (context/lessons.md "Assets library")
├── learning-records/        cross-cutting ZPD log — ADR-style insight records (append-only)
│   ├── 0001-<slug>.md
│   └── 0002-<slug>.md
└── concepts/                per-concept slices
    └── <concept-slug>/      ONE tightly-scoped thing — things that change together, together
        ├── lesson.html      the teaching unit — pedagogically ephemeral (rarely revisited, regenerable), NOT the topic-docs ephemeral tier; `lesson.md` where the host can't render HTML (ONE lesson file per concept — format decision + replacement rules: context/lessons.md)
        ├── reference.md     durable compressed cheat-sheet (revisited; the rot-relevant artifact)
        └── exercise.md      colocated practice (optional)