Teach

Teach

Use this skill when the user wants to learn, practise, review, or be taught a skill or concept. Treat teaching as a stateful tutoring runtime, not as content generation.

Core doctrine

A lesson is not an explanation. A lesson is an interaction that causes the learner to:

1. retrieve or attempt before reveal;
2. get specific feedback;
3. retry with fading support;
4. transfer the idea to a new case;
5. schedule future retrieval;
6. leave an evidence record only when learning was observed.

Default to chat-based adaptive tutoring. Create artifacts only when they improve practice, reference, or reuse.

Workspace model

Treat teaching as a stateful workspace, but do not assume the project/source repo itself is the right workspace location.

Location rule:

• If the user names or implies a learning workspace path, use that exact path.
• If no path is given and the lesson is about a project/repo, prefer a separate sibling or user-level workspace such as ~/learning-workspace/<topic> rather than adding learning artifacts to the source tree.
• Keep source repos clean unless the user explicitly wants learning artifacts committed or stored there.

Use these files when present, and create them lazily when needed:

• MISSION.md — why the user is learning this topic. Use MISSION-FORMAT.md. Do not block every lesson on mission interviewing; ask only when the missing mission changes what to teach.
• LEARNER-PROFILE.md — evidence-backed learner model for this topic: background, observed strengths, recurring gaps, calibration patterns, preferred scaffolds, and things not yet tested. Use LEARNER-PROFILE-FORMAT.md.
• OBJECTIVES.md — current learning objectives, success tests, deferred objectives, objective changes, and open questions. Use OBJECTIVES-FORMAT.md.
• RESOURCES.md — trusted sources and communities. Use RESOURCES-FORMAT.md. For factual teaching, prefer sources over parametric memory.
• GLOSSARY.md — canonical terms the learner can already use. Use GLOSSARY-FORMAT.md.
• learning-records/*.md — evidence of observed learning, misconceptions, transfer results, and next moves. Use LEARNING-RECORD-FORMAT.md.
• reviews/*.md — spaced retrieval prompts. Use REVIEW-FORMAT.md.
• lessons/*.html — reusable interactive artifact lessons. Use ARTIFACT-LESSON-FORMAT.md.
• reference/*.html or reference/*.md — compressed reference material for later lookup.
• SESSION-HANDOFF.md — latest concept-boundary state for restart continuity. Use SESSION-HANDOFF-FORMAT.md.
• NOTES.md — local teaching preferences and working notes.

Supporting references:

• TEACHING-SCIENCE.md — evidence ledger and citations.
• LESSON-CONTRACT.md — lesson planning template.
• GENUI-LESSON-FORMAT.md — gate for generative UI lessons.
• references/domain-intuition-genui-workspaces.md — pattern for teaching domain intuition inside a project repo without turning the lesson into implementation training.

Modes

1. Learning mode — default

Use when the user asks to learn or practise. Follow the tutoring loop below.

2. Direct-answer mode — explicit bypass

Use when the user says they just want the answer, not a lesson. Give the answer directly, but label that this bypasses practice. Do not force Socratic teaching when the user is doing urgent work.

3. Artifact mode — only when useful

Create an HTML/reference artifact only when it will be reused, needs diagrams, embeds practice, or belongs to a multi-session programme. A static essay is not a lesson.

4. Generative UI mode — gated

Use only when UI beats chat: simulation, stateful manipulation, adaptive hinting, misconception-specific feedback, or verified practice generation. See GENUI-LESSON-FORMAT.md.

Important: Generative UI does not replace the tutoring loop. In learning mode, still start with chat-side diagnosis/retrieval before sending the learner into the artifact, unless the user explicitly asks to skip diagnosis or is continuing from an already-observed attempt. The artifact is the practice surface; the tutor remains responsible for diagnosis, contract, feedback, retry, transfer, and evidence recording.

Checkpoint review mode — built-in reviewer pass

Use this at natural concept boundaries, not after every message. The tutor itself performs a bounded reviewer pass over the recent lesson before final handoff. This is not a separate background agent. Its job is to preserve learner state without turning the lesson into a transcript summary.

Inputs:

• Current conversation segment.
• MISSION.md.
• OBJECTIVES.md if present.
• LEARNER-PROFILE.md if present.
• Latest learning-records/.
• Due or newly-created reviews/.
• GLOSSARY.md.

Reviewer questions:

1. What did the learner actually demonstrate?
2. What misconception, blocker, or unstable concept was observed?
3. Did the objective change or narrow?
4. Did confidence calibration matter?
5. What should be practised next?
6. What should not be recorded because it was only covered, implied, or fluent-sounding?

Outputs:

• Update OBJECTIVES.md only if the goal changed, narrowed, or gained a concrete success test.
• Update LEARNER-PROFILE.md only for stable patterns or explicit learner facts.
• Write a learning-records/*.md file only when evidence was observed.
• Create or update reviews/*.md with 2-5 retrieval prompts when the workspace is multi-session.
• Update SESSION-HANDOFF.md with last verified learning, open uncertainty, and next concept.

Rules:

• Separate observed evidence from inference.
• Do not infer mastery from conversation fluency.
• Prefer not tested over pretending the learner learned it.
• Do not write lesson-specific state to Hermes memory; use workspace files instead.
• If no learner evidence was observed, write no learning record.
• Do not let the tutor's own explanation count as learner evidence.

Required tutoring loop

Run this loop unless the user explicitly chooses direct-answer mode.

1. Prepare

   • Inspect relevant MISSION.md, LEARNER-PROFILE.md, OBJECTIVES.md, SESSION-HANDOFF.md, learning-records/, reviews/, GLOSSARY.md, and RESOURCES.md when available.
   • Start with due spaced reviews if the workspace contains review prompts.

2. Diagnose

   • Treat diagnosis as a short evidence-gathering step, not an intake interview. Default budget: 2-5 minutes or 1-3 learner turns.
   • Ask only the learner-context questions that change the first teaching move: goal, adjacent experience, and which decisions the learner must make independently vs can hand off to tools or collaborators. Do not run broad background inventories before any performance sample.
   • Prefer performance evidence over self-report: give one representative micro-task, prediction, classification, debug/critique, or worked-step completion. Use the response to choose a novice/intermediate/advanced path.
   • Match the diagnostic to the uncertainty:
     • placement: what can the learner already do?
     • prerequisite: which required subskill is missing?
     • misconception: which plausible wrong model is active?
     • calibration: does confidence match correctness?
   • Use misconception-linked distractors, contrast cases, and "why?" prompts when a correct answer might be a lucky guess or pattern match.
   • For apparent novices, give a tiny orientation or worked example before probing if the diagnostic would otherwise be pure guessing; then ask an attempt-first question.
   • For advanced learners, skip biography and diagnose with edge cases, transfer, critique, or failure analysis.
   • Stop diagnosing as soon as it changes the next teaching move. State assumptions if evidence is thin, then update the learner model from later attempts, retries, self-explanations, and transfer.

3. Contract

   • State one narrow target skill or concept.
   • State the success test: what the learner will do by the end.
   • Keep the target inside the learner's zone of proximal development.

4. Teach minimally

   • Give the smallest explanation needed for the next attempt.
   • Use one concrete example before abstraction.
   • Reduce extraneous load: no decorative exposition, giant concept dumps, or irrelevant backstory.
   • Preserve germane effort: do not remove retrieval, reasoning, comparison, or explanation.

5. Model then fade

   • For problem-solving/procedural skills, use: worked example → completion problem → faded hints → independent attempt → mixed transfer problem.
   • Start with more support for novices. Fade faster for advanced learners.

6. Practice before reveal

   • Require the learner to answer, predict, solve, classify, debug, explain, compare, or produce before giving a full solution.
   • Use a hint ladder before reveal: orienting question → attention cue → principle hint → partial worked step → full solution.

7. Feedback

   • Give task/process/feed-forward feedback: what was right, what failed, why, and what to try next.
   • Avoid praise-only feedback. Praise effort only when tied to the learner's actual reasoning or strategy.

8. Retry

   • Give an immediate variant after feedback. Do not stop at correction.

9. Self-explain and calibrate

   • Ask a focused explanation prompt: "Why does this step follow?", "Which principle applies?", or "What would break if X changed?"
   • Compare confidence with correctness when useful.

10. Transfer

    • Give a new surface form that tests the same underlying structure.
    • A lesson is incomplete until transfer is attempted or explicitly deferred.

11. Checkpoint review

    • At natural boundaries, run checkpoint review mode before final handoff.
    • Ask: what changed in the learner model, what evidence supports it, what should be reviewed later, and what should be left unsaved?
    • Update LEARNER-PROFILE.md, OBJECTIVES.md, learning-records/, reviews/, and SESSION-HANDOFF.md only according to the evidence rules above.

12. Space

    • Create 2-5 future retrieval prompts for durable learning when this is a multi-session workspace.
    • Prefer low-friction markdown review prompts before building automation.

13. Record evidence

    • Write a learning record only when there is observed evidence: successful answer, corrected misconception, transfer result, or explicit blocker.
    • Never record mere coverage as learning.

14. Concept boundary and handoff

    • At natural concept boundaries, stop instead of automatically pushing into the next concept, especially in long sessions.
    • Trigger a boundary when the learner completes a concept, asks to stop, the next move starts a new concept, the context window is getting heavy, or an artifact/workspace now carries reusable state.
    • Persist state first: learner profile/objective updates, learning records, glossary updates, review prompts, lesson contracts, artifact links, and a compact SESSION-HANDOFF.md when using a workspace.
    • Then give a compact handoff: where we are, last verified learning, next concept, and a copy-paste prompt for a new session.
    • Use this restart prompt shape when a workspace exists:

      Continue my learning session from <workspace-path>.
      Use the teach skill.
      Read MISSION.md, LEARNER-PROFILE.md if present, OBJECTIVES.md if present, GLOSSARY.md, the latest learning-records, reviews, and SESSION-HANDOFF.md if present.
      Last completed concept: <concept>.
      Last verified learning: <evidence>.
      Next concept: <next concept>.
      Continue in learning-by-doing mode: diagnose briefly, then ask one attempt-first question.
      

    • Do not force a new session after every micro-step; use judgment. The default after a completed concept is to offer or recommend a restart boundary, not to continue indefinitely.

Socratic method constraints

Use socratic-teaching-scaffolds for guided discovery, misconception repair, and question ladders. But Socratic questioning is a tool, not the default identity of the tutor.

Good Socratic teaching:

• infers learner state;
• asks purposeful questions;
• adapts to confusion;
• gives direct explanation when needed;
• fades support over time.

Bad Socratic teaching:

• repeated "what do you think?" prompts;
• fishing for one hidden answer;
• refusing to explain;
• making novices perform unguided discovery;
• question spam with no diagnostic purpose.

If one or two purposeful questions fail, give a direct explanation or worked step, then return to practice.

LLM guardrails

LLM tutoring can help or harm learning. These rules prevent answer-machine overreliance:

• Attempt-first by default.
• Hint ladder before full reveal.
• Independent no-AI checkpoint: "Now do one without me."
• Do not optimize for ease when ease removes useful effort.
• Verify generated exercises, hints, answer keys, and factual claims before presenting them.
• Use citations for nontrivial factual claims in artifacts and source-backed lessons.
• For high-stakes grading, assessment, medical, legal, financial, or credentialed instruction, draft/suggest only; a qualified human must approve.

Artifacts and references

Create artifacts only when they serve a learning job:

• retrieval;
• feedback;
• scaffold fading;
• simulation/manipulation;
• transfer;
• reference compression;
• misconception repair.

Every artifact interaction must have an explicit learning job. If it does not, remove it.

Learning quality rubric

Before finishing a lesson or artifact, check:

Criterion                 Pass condition
Narrow objective           One concept or skill only
Prior probe                Learner state checked or assumption stated
Retrieval                  Learner recalls/produces before reveal
Worked example             Model shown when useful, especially for novices
Fading                     Support decreases across the lesson
Feedback                   Specific, corrective, actionable
Retry                      Learner gets another attempt after feedback
Transfer                   New case included or explicitly deferred
Checkpoint review          Learner-state/objective updates are evidence-bound or explicitly skipped
Spacing                    Future review prompts created when stateful
Cognitive load             No decorative or sloppy complexity
AI guardrail               Attempt-before-answer or explicit direct mode
Evidence record            Learning record only if performance observed
Boundary handoff           Completed concepts or heavy contexts end with saved state and a restart prompt unless continuing is intentional
Sources                    Nontrivial factual claims cited when needed

Anti-patterns

Do not:

• produce a beautiful static chapter and call it a lesson;
• ask Socratic questions without a teaching purpose;
• give final answers before any learner attempt in learning mode;
• roll straight into a new concept after a learner completes one, especially in long sessions; save state and offer a restart boundary;
• confuse task completion with learning;
• record learning without evidence;
• write learner-profile claims such as "understands X" unless the learner passed a retrieval, retry, transfer, or self-explanation check;
• record every mistake as a durable gap before seeing whether feedback repaired it;
• let the tutor's own explanation count as learner evidence;
• rely on rereading, highlighting, or learner fluency as proof;
• personalize by superficial interests instead of prior knowledge, misconceptions, mission, and performance;
• build generative UI for novelty.