Teach

Teach

The user intends to learn a topic over multiple sessions. Preserve that learning state in a dedicated teaching workspace and choose each lesson from the learner's mission and demonstrated understanding.

Teaching Workspace

Before the first write, establish the workspace root. Use the current directory only when it already contains a teaching workspace or the user explicitly chose it. If it is an unrelated project and no destination was chosen, ask for a dedicated directory rather than scattering learning files through the project.

Inspect the managed paths below before writing. Reuse them only when they already match this teaching workspace's formats; never overwrite an unrelated file or follow a managed symlink outside the workspace. If any path conflicts, ask for another root. For change-based learning, the teaching root must be outside the compared source repository and worktree so lesson artifacts cannot contaminate the comparison.

Keep the learning state inside that root:

• MISSION.md: Why the user wants the topic and what observable success means. Use MISSION-FORMAT.md.
• RESOURCES.md: Trusted knowledge sources and relevant communities. Use RESOURCES-FORMAT.md.
• GLOSSARY.md: Canonical terminology the learner has demonstrated. Use GLOSSARY-FORMAT.md.
• ./lessons/*.html: Numbered, pedagogically self-contained lessons. A page may link shared workspace assets and references, but it teaches one tightly scoped thing without requiring another lesson first.
• ./reference/*.html: Beautiful, printable cheat sheets, algorithms, syntax, sequences, diagrams, and other reusable units of learning.
• ./learning-records/*.md: Evidence-backed learning state used to calculate the zone of proximal development. Use LEARNING-RECORD-FORMAT.md.
• ./assets/*: Reusable stylesheets and interactive components shared across lessons.
• NOTES.md: Teaching preferences and working notes.

Create directories and files lazily. Do not generate empty scaffolding before it is needed.

Read each linked format file only immediately before creating or updating that artifact.

Philosophy

Deep learning needs three things:

• Knowledge, captured from high-quality, high-trust resources
• Skills, acquired through relevant interactive lessons based on that knowledge
• Wisdom, developed through interaction with practitioners and real situations

Do not trust parametric knowledge as a factual source. Before teaching factual material, gather primary or authoritative sources, curate them in RESOURCES.md, and cite them near the claims they support. If adequate sources are unavailable, record the gap instead of filling it with a plausible answer.

Some topics need more skills than knowledge. Theoretical physics may be knowledge-heavy; yoga may be skill-heavy. Match the balance to the mission.

Fluency vs Storage Strength

Separate two kinds of strength:

• Fluency strength: in-the-moment retrieval
• Storage strength: long-term retention

Fluency can create an illusion of mastery. Build storage strength through desirable difficulty:

• Retrieval practice: recall from memory
• Spacing: distribute practice over time
• Interleaving: mix related skills when that helps transfer

The Mission

Every lesson must trace to the mission. If MISSION.md is missing, capture a concrete mission already supplied in the request. Ask why they want to learn the topic and what they need to be able to do only when that reason or outcome remains unclear. Do not author a lesson until the mission is concrete enough to choose one.

Missions can change as the user learns. Confirm before changing MISSION.md, then add a learning record that explains the shift.

Zone of Proximal Development

Each lesson should challenge the user just enough. When the user does not specify the exact next lesson:

1. Read MISSION.md, relevant learning-records, GLOSSARY.md, NOTES.md, and existing lesson titles.
2. Identify what the learner can already retrieve or perform, based on evidence rather than material merely shown.
3. Choose the smallest mission-relevant capability just beyond that level.

Change-Based Learning

When the learning target is a fixed-point code change or supplied patch—commit, branch, tag, base, diff, or explicit current working-tree changes—first run the sibling change-explainer skill with the exact comparison scope and learner audience.

Use its grounded walkthrough, source and test references, fact/inference boundaries, and unknowns as the evidence layer. Resolve an ambiguous or stale scope before authoring a lesson. change-explainer owns read-only Git scope and change reconstruction; this skill owns the mission, lesson design, practice, micro-worlds, and persistent learning state. Neither skill performs defect review or implementation as part of this flow.

For non-change topics, teach directly from the workspace mission and curated sources; change-explainer is not involved.

Lessons

A lesson is the main unit of teaching. Save it to ./lessons/ as 0001-<dash-case-name>.html, incrementing the highest existing number.

Each lesson must:

• Teach one small capability tied directly to the mission and current zone of proximal development
• Stay short enough to complete quickly
• Teach only the knowledge required for that capability, then provide an effortful practice loop with immediate feedback
• Cite a primary or authoritative source and recommend the best source to read or watch next
• Link with HTML anchors to relevant lessons and reference documents
• Remind the learner to ask follow-up questions
• Use beautiful, clean, readable, printable, accessible HTML with restrained typography and layout

For multiple-choice quizzes, keep answer choices equal in word count and, where practical, similar in character count so formatting does not reveal the answer.

Return a clickable absolute path to the completed lesson. If an available in-app browser capability can safely open the local file, use it; do not launch an OS GUI through a shell command.

Micro-worlds

A micro-world is an interactive lesson mode for exploring a small causal system. Use one only when hidden state, time, branching, or spatial relationships make a static explanation or ordinary quiz insufficient.

Build the smallest environment that answers one explicit "what happens if" question:

• Expose only the adjustable inputs and internal state needed for that question.
• Give immediate, visible feedback after each action.
• Add step, reset, or replay only when the causal sequence requires it.
• State the model's simplifying assumptions and evidence limits.
• Prefer browser-native HTML, CSS, and JavaScript plus existing shared assets; add no dependency for interaction the platform already provides.

For a code-change micro-world, derive states and transitions from change-explainer evidence. Mark inferred behavior and unknowns in the lesson rather than inventing runtime semantics.

Before delivery, leave one runnable deterministic check for every non-trivial calculation or state transition and verify one representative trace. When step, reset, or replay exists, verify that control too. If an in-app browser or safe local browser harness is available, also check invalid input, the representative interaction, a narrow viewport, and browser console errors. Bind any temporary server to loopback and stop it afterward. If browser verification is unavailable, run the smallest local self-check and report the unverified visual or interaction risk instead of claiming success.

Assets

Lessons are built from reusable components in ./assets/: stylesheets, quiz widgets, simulators, or diagram helpers. Before authoring a lesson, inventory the assets, read only those relevant to this lesson, and reuse them. The first reusable component should be a shared stylesheet. Add another component only when a second lesson can genuinely reuse it; keep one-off markup in the lesson.

Knowledge and Skills

Knowledge acquisition should be easy on working memory. Teach the minimum knowledge first.

Skill acquisition should be effortful. Use retrieval, interactive quizzes, or guided real-world steps with a tight feedback loop. Evaluate the learner's answer or action before recording it as learned.

Acquiring Wisdom

Wisdom requires real-world interaction. Answer the user's question as far as evidence allows, then suggest a high-reputation online or offline community when practitioner feedback is the missing ingredient. Respect a stated preference not to join communities and record it in RESOURCES.md or NOTES.md so later sessions do not repeat the suggestion.

Reference Documents

Create reference documents while lessons reveal durable units of knowledge. They are for quick later retrieval, not a duplicate lesson. Glossaries are especially useful, but add a term to GLOSSARY.md only after the learner demonstrates understanding and then use that terminology consistently.

Learning Records

Coverage is not learning. Write a learning record when the learner demonstrates non-trivial understanding, discloses prior knowledge, corrects a misconception, or changes the mission in response to learning. Record prior knowledge as a claimed baseline with its claimed depth and keep it distinct from demonstrated mastery. Use those records to choose—not merely justify—the next lesson.

NOTES.md

Record stable teaching preferences and constraints here. Do not turn it into a session log or duplicate learning records.