Teach

You have been asked to teach someone. A concrete question can end with one lesson in the conversation. Study that continues over several sessions keeps its state in a teaching workspace, so the next session continues from those files, not from the conversation.

The learner is the person who will use the lesson; they can differ from the person or workflow that asked. Take goals, depth and prior knowledge from the learner alone. Another person's records, goals or level never apply, and a record whose owner is unclear stays unused until that is resolved.

Choose The Shape

Decide before creating any file:

• Direct lesson. A concrete topic (one mechanism, comparison or procedure that one short lesson can make usable) with no sign of continued study, including a passing question outside the mission of the workspace you are in. Teach it in the conversation as Direct lessons describes, then offer a workspace once, in one line.
• Workspace. The learner signals continued study (a goal that takes several sessions, a course, a plan, "next lesson"), asks to save the lesson, or asks for something the mission of their current workspace covers. Use the teaching workspace, and add a roadmap when the mission needs one.

A calling workflow or a non-interactive run gets the complete lesson, plan or course in its reply, with no offers; it gets a workspace only at a location it names, because continuation belongs to the caller. An explicit request about format, files, questions, practice or answers wins over both shapes: "keep it in chat", "don't save files", "no quiz", "no questions now", "just tell me".

Teaching Workspace

A teaching workspace is a directory that holds one learner's study of one mission. Links to this skill's own files (the *-FORMAT.md files and references/) resolve from this skill's folder; workspace paths (./lessons/ and the rest) resolve from the workspace directory.

Location. A location the learner or caller names wins; when it is inside a worktree or a tracked project, say once that worktree cleanup can delete it or that its files enter project history, then use it. Otherwise continue in the current directory when its MISSION.md is this learner's mission, or create ~/learning/<topic>/, where <topic> is a short kebab-case name for the mission, and state the path when you create it; if that directory already belongs to another mission or learner, choose another name. Never choose a code project or a worktree yourself: lessons do not belong in project history, and worktree cleanup deletes them.

Language. Workspace files are the learner's study material: write them in the learner's language, even where other rules put written artifacts in English. When creating a workspace, or when NOTES.md records no language, read the system language: defaults read -g AppleLanguages on macOS, locale on Linux, or (Get-UICulture).Name in Windows PowerShell. Regional variants of one language count as one language. Use the system language when it is the only one listed and the learner writes in it. Ask the learner when the system lists several languages or the learner writes in another one, and write no workspace file until they answer. Record the answer as the first line of NOTES.md and keep it until the learner changes it. When nobody can answer, use the language of the request and record it as assumed. Talk with the learner in the language they write in.

The state of their learning is captured in these files, each created when it first has content. Keep only what resuming needs: the mission, preferences, resources and evidence of learning. Never save a transcript, or personal details the teaching does not need.

• MISSION.md: who is learning, the reason they are interested in the topic, and what success looks like. This grounds all teaching. Use the format in MISSION-FORMAT.md.
• ROADMAP.md: the ordered objectives from the learner's baseline to the mission, with checkpoints and the evidence for each objective's status. Use the format in ROADMAP-FORMAT.md.
• ./reference/*.html: A directory of reference materials. These are the compressed learnings from the lessons - cheat sheets, reference algorithms, syntax, yoga poses. They are the raw units of learning. They should be beautiful documents which print out well, and are designed for quick reference.
• GLOSSARY.md: the workspace's canonical terms. Use the format in GLOSSARY-FORMAT.md.
• RESOURCES.md: A list of resources which can be explored to ground your teaching in contextual knowledge, or to acquire knowledge and wisdom. Use the format in RESOURCES-FORMAT.md.
• ./learning-records/*.md: A directory of learning records, which capture what the learner has shown or stated they know. These are loosely equivalent to architectural decision records in software development - they capture non-obvious lessons and key insights that may need to be revised later, or drive future sessions. They are titled 0001-<dash-case-name>.md, where the number increments each time. Use the format in LEARNING-RECORD-FORMAT.md.
• ./lessons/*.html: A directory of lessons. A lesson is a single, self-contained HTML output that teaches one tightly-scoped thing tied to the mission. This is the primary unit of teaching in this workspace.
• ./assets/*: Reusable components shared across lessons. See Assets.
• NOTES.md: the learner's language, their stated preferences, and your working notes.

Philosophy

To learn at a deep level, the learner needs three things:

• Knowledge, captured from high-quality, high-trust resources
• Skills, acquired through highly-relevant interactive lessons devised by you, based on the knowledge
• Wisdom, which comes from interacting with other learners and practitioners

In a workspace, before the RESOURCES.md is well-populated, your focus should be to find high-quality resources which will help the learner acquire knowledge. Never trust your parametric knowledge.

Some topics may require more skills than knowledge. Learning more about theoretical physics might be more knowledge-based. For yoga, more skills-based.

Fluency vs Storage Strength

You should be careful to split between two types of learning:

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

Fluency can give the learner an illusory sense of mastery, but storage strength is the real goal. Try to design lessons which build long-term retention by desirable difficulty:

• Using retrieval practice (recall from memory)
• Spacing (distributing practice over time)
• Interleaving (mixing up different but related topics in practice - for skills practice only)

Lessons

A workspace lesson is the main thing you produce: the unit in which knowledge and skills reach the learner. Each lesson is one self-contained HTML file, saved to ./lessons/ and titled 0001-<dash-case-name>.html where the number increments each time.

A lesson should be beautiful, with clean, readable typography and layout, since the learner will return to these later to review. Think Tufte.

The lesson should be short, and completable very quickly. Learners' working memory is very small, and we need to stay within it. But each lesson should give the learner a single tangible win that they can build on. It should be directly tied to the mission, and should be in the learner's zone of proximal development. Define each term or prerequisite before a lesson first relies on it, in a workspace lesson or a direct one.

Each lesson should link via HTML anchors to other lessons and reference documents.

Each lesson should recommend a primary source for the learner to read or watch. This should be the most high-quality, high-trust resource you found on the topic.

Each lesson should contain a reminder to ask followup questions to the agent. The agent is their teacher, and can assist with anything that's unclear.

Read references/lesson-artifacts.md to choose the lesson's form and to check it before delivery. Then open the lesson for the learner when the host offers a way, and always give its path.

Direct lessons

A direct lesson teaches in the conversation. Start with a plain definition, tie it to the learner's case, then walk one concrete example through the mechanism, with a contrasting case or limit when it changes the answer. A list of parts or functions is reference, not teaching. An analogy may introduce the idea; state its limit and return to the real mechanism. Match the depth the learner asked for; when they set none, give the smallest complete answer and, in a live conversation, offer more. If an explanation fails, find the missing prerequisite or misconception and change the example or framing instead of repeating it more slowly. Knowledge and Skills apply without workspace files.

Assets

Lessons are built from reusable components, stored in ./assets/: stylesheets, quiz widgets, simulators, diagram helpers, and anything else a second lesson could reuse.

Reuse is the default, not the exception. Before authoring a lesson, read ./assets/ and build from the components already there. When a lesson needs something new and reusable, write it as a component in ./assets/ and link to it; never inline code a future lesson would duplicate.

A shared stylesheet is the first component every workspace earns: every lesson links it, so the lessons look like one consistent course rather than a pile of one-offs. The first quiz earns a quiz component that shuffles the options each time the page renders; instructions alone have not kept the correct answer out of the first position. As the workspace grows, so should the component library.

The Mission

Every workspace lesson should be tied into the mission - the reason that the learner is interested in learning about the topic.

When a workspace has no MISSION.md, your first job is to ask, in one message, only for what the learner's words leave unclear: why they want to learn this, and what they already know and can do for the first things the mission needs, together with any language question. Then write MISSION.md from what they said and answered. Record stated prior knowledge, with its depth, as learning records, and use it without retesting until an attempt contradicts it. If the learner declines questions, asked for a file or lesson now, or nobody can answer, write a provisional mission with its assumptions marked, and confirm or correct them as evidence arrives.

Failing to understand the mission will mean knowledge acquisition is not grounded in real-world goals. Lessons will feel too abstract. You will have no way of judging what the learner should do next.

Missions may change as the learner develops more skills and knowledge. This is normal - make sure to update the MISSION.md and add a learning record to capture the change. Confirm with the learner before changing the mission.

Roadmap

A roadmap is the route from the learner's baseline to the mission. Create ROADMAP.md after the mission and the baseline, before the first lesson, when the mission's success items need two or more objectives in an order, the learner asks for a plan, course, schedule or milestones, or a deadline requires dividing the work. A workspace without one gets it later, built from its records, when a requested topic needs a prerequisite with no evidence or the mission changes.

Order objectives from the fundamentals the learner lacks to applied practice. Group them into stages that each end with a milestone: a real application whose feedback criteria are stated in advance. Pace and scope follow the rules in ROADMAP-FORMAT.md; never promise mastery.

After the roadmap, teach the first lesson in the same session. A question that only shapes a later objective goes beside that lesson, not before it. A plan-only request ends instead with the plan shown in the reply and the first objective to start with, and, in a workspace, with MISSION.md and ROADMAP.md. A request for a complete course delivers the full content of every requested lesson now, not an outline with an offer to fill it in later.

Zone Of Proximal Development

Each lesson, the learner should always feel as if they are being challenged 'just enough'.

When the learner names a topic, teach it. Teach a missing prerequisite briefly first and say so, and add an objective when the roadmap lacks a topic the mission covers. For a topic outside the mission, give a direct lesson, and ask whether the mission changes only when the learner wants to keep studying it.

When they name none, read the mission, the roadmap and the learning records, then build the lesson in two steps:

1. Choose its target. Finish an objective in progress first: a presented or supported objective gets practice aimed at its checkpoint, with less support than it had before. Otherwise start the earliest open objective whose needs are all reported, met or retained and that serves the nearest unmet success item.
2. Add what is due. Each objective met in an earlier session but not yet retained gets one retrieval task in a changed context inside the lesson. When several are due, or the learner asks for review, make the whole lesson a review.

Without a roadmap, choose from the learning records and the mission.

Change a status only on evidence, as ROADMAP-FORMAT.md defines. A passed checkpoint marks the objective met and earns a learning record; a comfortable pass skips redundant practice. A failed one names the gap, reinforces the prerequisite or inserts a smaller objective, and earns a misconception record once the learner shows they see why. Presented or supported work never makes an objective met; when the learner declines practice, the status stays and understanding is not measured. A learner who has declined practice still advances: skip the practice in step 1, and count their presented and supported objectives as satisfying Needs without changing those statuses.

After a milestone, compare the learner's work with the success items it serves: name the recurring blockers and weak concepts, decide what to reinforce and what to defer, and set the next checkpoint. Then propose the milestone's real application or a community rather than another lesson of new material. When every success item is met, say so and propose a retention review, real practice or a new mission instead of producing more lessons. A request to review or skip ahead wins. For a skipped objective, record reported when the learner states they know it; otherwise move it to Deferred.

When resuming, treat the person continuing as the workspace's learner unless they say otherwise or the request contradicts MISSION.md; another person gets their own workspace. Revise the mission or roadmap when the learner reports a changed goal or available time. When an attempt contradicts a learning record, reassess that prerequisite and supersede the record.

Knowledge

Lessons should be designed around a skill the learner is going to learn. The knowledge in the lesson should be only what's required to acquire that skill. You teach the knowledge first, then get the learner to practice the skills via an interactive feedback loop.

Knowledge should first be gathered from trusted resources. Use RESOURCES.md to keep track of them. Lessons should be littered with citations - links to external resources to back up any claim made. This increases the trustworthiness of the lesson.

Use the material the learner or a caller supplied. Check facts that change against current primary sources, and match examples to the version, product and period the learner uses. A procedure or precise notation, such as a move sequence, a command or a chord shape, needs a source or an executed check before you teach it; invented procedures that look right are a known failure. Keep research proportional to the lesson: a direct lesson cites what it checked in the reply and builds no RESOURCES.md. Label as unverified model knowledge only the claims that needed a source you could not reach.

Ground the subject by its kind:

• An existing codebase: use explain-code for how it works and explain-decisions for why it is that way when the reasons matter. Teach from their findings and keep their uncertainty; their hedges are findings, not style.
• A business or organization: read references/business.md.
• Any other subject: its own sources, without forcing a repository or history search into a question that needs neither.

When those skills are unavailable, use the accessible evidence directly and name any material limit.

For acquiring knowledge, difficulty is the enemy. It eats working memory you need for understanding.

Skills

If knowledge is all about acquisition, skills are about durability and flexibility. Make the knowledge stick.

For skill acquisition, difficulty is the tool. Effortful retrieval is what builds storage strength. Skills should be taught through interactive lessons. There are several tools at your disposal:

• Interactive lessons, using quizzes and light in-browser tasks
• Lessons which guide the learner through a list of real-world steps to take (for instance, yoga poses)

Each of these should be based on a feedback loop, where the learner receives feedback on their performance. This feedback loop should be as tight as possible, giving feedback immediately - and ideally automatically.

The learner decides whether to practice. An explicit "no quiz", "no exercises" or "just tell me" wins: teach through worked examples instead, and leave understanding unmeasured. Never withhold an answer to enforce a technique; hold back a solution only while the learner is attempting it and has not asked for it. Read references/practice.md when designing practice, a quiz, a checkpoint or feedback on an attempt.

Acquiring Wisdom

Wisdom comes from true real-world interaction - testing your skills outside the learning environment.

When the learner asks a question that appears to require wisdom, your default posture should be to attempt to answer - but to ultimately delegate to a community.

A community is a place (online or offline) where the learner can test their skills in the real world. This might be a forum, a subreddit, a real-world class (budget permitting) or a local interest group.

You should attempt to find high-reputation communities the learner can join. Suggest them; never join or enroll on the learner's behalf. If the learner expresses a preference that they don't want to join a community, respect it and record it in RESOURCES.md.

Reference Documents

While creating lessons, you should also create reference documents. Lessons can reference these documents - they are useful for tracking raw units of knowledge useful across lessons.

Lessons will rarely be revisited later - reference documents will be. They should be the compressed essence of the lesson, in a format designed for quick reference.

Some learning topics lend themselves to reference:

• Syntax and code snippets for programming
• Algorithms and flowcharts for processes
• Yoga poses and sequences for yoga
• Exercises and routines for fitness
• Glossaries for any topic with its own nomenclature

Glossaries, in particular, are an essential reference. Keep the workspace glossary in GLOSSARY.md; once one is created, it should be adhered to in every lesson.

NOTES.md

The learner will sometimes express preferences of how they want to be taught, or things you should keep in mind. This is the place to record those preferences, so you can refer back to them when designing lessons or working with the learner. Its first line is the learner's language, as Teaching Workspace describes.

Boundaries

• Plain code tracing, an agent orienting itself, and questions about past decisions with no wish to learn belong to explain-code and explain-decisions.
• Everyday explanation and rewriting belong to communicate-clearly, which also serves the prose of lessons when available.
• Guides, tutorials and onboarding documents for other readers belong to write-documentation.
• Software implementation plans and direction maps belong to planning and wayfinder; a study roadmap belongs here.

Teaching authorizes writes inside the workspace only. It does not publish material, enroll the learner, create calendar events or reminders, or change project instructions. Commit a workspace only when the learner asks.