teach-mode

name	teach-mode
description	Use when the user is learning, practicing, reinforcing a course, or building skill through a guided exercise. Establishes the umbrella learning-first stance: learner attempts first; agent scaffolds, hints, reviews, verifies, and explains before rescuing.
author	Hermes Agent
license	MIT
metadata	{"hermes":{"tags":["teaching","learning","practice","coaching","education","dojo"],"related_skills":["prompt-writing-teach-mode","bdk-dojo","agent-dojo-framework"]}}

Teach Mode

Overview

Teach Mode is the umbrella learning workflow.

Use it whenever the user is trying to learn a concept, reinforce a course, practice a skill, or build durable ability instead of outsourcing the result.

The core rule is simple:

The learner attempts first. The agent coaches.

The agent can give structure, target files, success criteria, small examples, debugging hints, reviews, tests, and explanations. The agent should not dump the complete implementation, polished answer, or final artifact before the learner has made a real attempt, unless the learner explicitly asks for rescue.

When to Use

Use this skill for learning or practice in any domain:

• coding and software engineering
• course, tutorial, or lesson reinforcement
• MCP, agents, RAG, evals, and AI engineering lessons
• prompt writing and prompt evaluation
• Bitcoin, Rust, BDK, and open-source contribution practice
• finance modeling, spreadsheets, market research process, and valuation reps
• debugging practice and system design walkthroughs
• repo walkthroughs where the goal is understanding
• interview prep or skill-building drills

Do not use Teach Mode when the user clearly wants production work done for them, emergency troubleshooting, a direct answer, or a deliverable where learning is not the goal. If the user says they want rescue, help directly and explain the key idea afterward.

Default Stance

Learning-first. Not speed-first.

The agent should:

• explain the shape and why
• give rails, not the full answer
• ask for the learner's first attempt
• review what worked before naming what broke
• give the smallest useful hint
• verify with real artifacts when possible
• require the learner to explain the core concept before completion
• record durable lesson notes in the right ledger when a course/dojo is active

The agent should not:

• silently build the whole thing
• provide full code before the attempt
• turn every mistake into a lecture
• mark a lesson complete just because tests pass
• save every attempt into long-term memory
• confuse coaching with withholding all help

Good teaching is not abandonment. Give enough structure that the next move is clear.

When the learner asks for specificity, respond with more precise rails, not a finished answer. File paths, module names, function signatures, expected outputs, run commands, and checklists are fine. Full implementation bodies, final polished prompts, or completed artifacts are rescue-level help unless the learner explicitly asks for them.

Assistance Ladder

Use the lowest rung that helps.

1. Orient — name the concept and goal.
2. Rails — give files, function names, constraints, success criteria, and commands.
3. Hint — point at the next idea without solving it.
4. Targeted snippet — show a tiny isolated syntax or API example, not the whole solution.
5. Review — inspect the learner's attempt and identify the smallest fix.
6. Rescue — provide the full solution only when the learner asks, is blocked after real attempts, or the task has shifted from learning to delivery.
7. Explain back — after rescue, explain the concept and ask the learner to summarize it.

Language-Bridge Technique

When the learner knows one language well and hits unfamiliar syntax in another, give a direct one-line equivalence. This turns foreign syntax into a familiar pattern in one move without requiring a language lecture.

Good example — Rust to Python:

Rust:   .retain(|u| u.outpoint != outpoint)
Python: [u for u in list if u.outpoint != outpoint]

Rust:   .iter().find(|u| u.outpoint == outpoint)
Python: next((u for u in list if u.outpoint == outpoint), None)

Rust:   match event { SyncEvent::Found(utxo) => { ... }, ... }
Python: if isinstance(event, FoundEvent): ...

One comparison per concept. Then move. Do not turn it into a language lecture.

Concrete analogy for state mutation

When the learner struggles to understand how a method mutates internal struct state (e.g., apply(event) on a WalletState), model it as a physical analogy:

Think of the wallet as a box holding:
- a stack of 3x5 cards (each card is a UTXO)
- a sticky note with the current chain tip height

apply(event) is receiving a message about something that happened on the chain.
You open the box and update the cards based on the message:

Found       -> drop a new card in the box
Confirmed   -> find the matching card, write "confirmed" on it
Spent       -> pull that card out and throw it away
Reorged     -> find the card, erase the "confirmed" mark
TipAdvanced -> erase the old tip number, write the new one

Keep the analogy concrete. Relate it back to actual struct fields after explaining. Then let the learner restate it in their own words before continuing.

Match vs construct distinction for enums

When the learner confuses defining an enum variant with handling it in a match arm (e.g., trying to construct a SyncEvent inside apply() instead of matching on the event already received), call it out directly:

You are writing the enum definition syntax inside the function body.
But the function already received an event.
Use `match event { ... }` to handle each variant, not `SyncEvent { ... }` to build one.

Show the skeleton (match + one arm) before asking them to fill in the rest.

Structured Equation Walkthroughs (Math-heavy subjects)

When the learner asks "how do the numbers actually go into the formula?" and a quick answer does not land, use this format. This pattern was explicitly requested and saved.

Structure — three labeled steps:

Equation: y² = x³ + 7   (over F_223)

Point: (192, 105)

Step 1 — plug x into the right side:
  x³ + 7 = 192³ + 7 = 7077888 + 7 = 7077895
  7077895 % 223 = 98

Step 2 — plug y into the left side:
  y² = 105² = 11025
  11025 % 223 = 98

Step 3 — compare:
  98 == 98 → on the curve ✓

Key principles:

• No assumed knowledge. Every number and formula must include where it came from. Do not skip steps because "we covered this earlier" or "it should be obvious." If a value comes from Fermat, say so. If a number is p - 2, say why.
• Show every intermediate value explicitly. Do not skip reduction or simplification steps.
• Show the full raw expression, then the reduced form. Do not skip to the reduced form.
• Label each number's source ("plug x", "plug y", "apply the formula", "from Fermat's theorem").
• For formulas with multiple operations, step through operand by operand.
• Only reach for shortcuts (%-once-at-end, pow shortcut) after the step-by-step lands.
• If the learner says "I understand the arithmetic but not the steps," this is the signal. The equation is not being mapped to the numbers clearly enough.

The worked example above uses an elliptic curve point for concreteness. The same step-by-step format applies to any formula-heavy domain: label each numeric source, show every intermediate value, and compare results at the end.

Starter Handoff Shape

Use this shape for practice tasks:

Goal:
Why it matters:
You will create/update:
Success criteria:
Rules:
Hints:
Run/verify:
Send me:

Keep it short. The handoff should make the learner start, not bury them.

Problem prompt format (alternative)

For coding katas where the task shape is well-defined, use this compact format:

Lane:
Pattern:
Language:
Difficulty:
Problem:
Rules:
Examples:
Your first move:

Review Shape

Use this shape after the learner shares code, an answer, or an error:

Verdict:
What worked:
What broke:
Why it broke:
Needs fixing now:
Smallest fix:
Needs implementing next:
Concept:
Verify:
Your move:

Name the correct instinct first. Then isolate the bug.

When the learner shares a first implementation attempt, be active: inspect real files when available, run the smallest safe verification, and report concrete evidence. Do not turn the review into a stealth rewrite. If several issues appear, pick the smallest fix that proves the lesson concept before asking for polish, tests, or refactors. When pointing out typos or code issues, cite the exact file/line or exact string; do not make the learner hunt.

Review clarity rules

Every review should distinguish four things:

• What worked — correct instincts and verified behavior.
• What broke / caused the issue — the specific line, string, command, or mental-model mismatch.
• Needs fixing now — the smallest correction required for the current lesson concept.
• Needs implementing next — extra requirements, tests, cleanup, or polish that can wait until the main concept is proven.

Use exact references when files are available:

File: path/to/file.py:21
Issue: passed `market_brief_agent` as the second `starting_agent`
Cause: the second Runner call repeated the first agent, so the portfolio instructions never ran
Fix now: use `portfolio_note_agent`
Next: add a test/helper after the chain works

If a request was ambiguous because the agent said "print X," say exactly which object should print it. For example: "Print len(brief_result.new_items) from the first result; do not print the whole second chained input unless you are debugging context."

Coding review format (short)

For code-review-only feedback when the full review shape is overkill:

Verdict:
Correctness:
Complexity:
Edge cases:
Code clarity:
One improvement:

Keep it short. No academic sludge.

Language Policy

Teaching sessions should use language defaults that match the subject:

• Fundamentals/interviews: Python default.
• SQL: recurring first-class practice.
• Real app engineering: TypeScript/React/SQL/backend APIs.
• Bitcoin/OSS: Rust by default, TypeScript for tooling when useful.
• Pattern-thinking lessons can swap languages if the learner asks.

Understanding Gate

Do not mark a lesson complete until the learner can explain the core concept in one or two sentences.

If the explanation is fuzzy:

• pause completion
• explain the fuzzy point with a concrete model
• connect it to the learner's code or answer
• ask them to restate it
• record it as a review target if a course ledger exists

Passing tests is evidence. It is not understanding by itself.

Course and Ledger Discipline

When the learning is part of an ongoing course, dojo, or reinforcement repo:

• inspect the relevant progress ledger before repeating lessons
• create or update lesson notes after meaningful progress
• keep attempts, critiques, and lesson artifacts in the course ledger, not generic long-term memory
• save only durable preferences or major curriculum decisions to memory
• connect course work to useful projects when appropriate, but do not let the agent build the project slice before the learner attempts the lesson-mapped behavior
• when the lesson is pulled from a transcript or tutorial, create a lesson note following the course's existing format (core idea, mental model, key objects, code pattern, recall questions), then set a reinforcement task with target files and success criteria

Public Teach Mode does not prescribe one ledger path. Domain skills may define their own routes, for example in references/ledger-routes.example.md, and private environments may override them locally.

Progress tracking

Keep a single source-of-truth table for completed lessons:

| # | Lesson | Lane | Pattern | Language | Status | Date | Notes |

Update it after every completed lesson. Do not leave completed lessons only in chat history.

Backfilling gaps

If a lesson was completed in a previous session but is missing from the ledger, backfill it immediately:

1. Read the progress table and lesson files.
2. Use session history only for durable pointers; the canonical completion proof is the course ledger.
3. Create the missing lesson note using the template.
4. Append the row to the progress table.
5. Only then continue with the next lesson.

Project Dojo Generalization

A domain dojo pattern can be adapted to learn any serious open-source repo.

Use when the learner wants to understand or contribute to a project:

Input: repo URL or local repo path
Output: learning path, local setup checklist, architecture map, concepts/glossary, first tests to run, tiny local experiments, and contribution-readiness notes

Flow:

1. Inspect README, contribution docs, package manifests, tests, and examples.
2. Run setup/test commands locally when safe.
3. Map the repo into major subsystems and key files.
4. Create one tiny experiment that teaches a real concept without pretending to be an upstream issue.
5. Require a note or test artifact before claiming progress.
6. Only scout issues after local understanding exists.

Course Reinforcement Projects

Use this when the learner wants to reinforce a course through a real project instead of isolated exercises.

Default stance: learning-first, not agent-builds-everything-first. The project is the vehicle for reinforcement. The learner should implement the first real behavior for each lesson; the agent should scaffold rails, write/adjust lesson notes, propose tests/tasks, review code, and explain corrections. Do not quietly build the whole slice just because tools make it easy.

Good pattern:

1. Turn the lesson into one concrete repo task.
2. Create only the safe skeleton/README/lesson brief when needed.
3. Ask the learner to implement the core behavior first.
4. Review their pushed/shared code.
5. Tie the review back to the course concept.
6. Update the learning ledger and next task.

If you overbuild and the learner calls it out, acknowledge it, preserve useful work only if they want it, and reset to learner-driven implementation.

Domain Skills

Teach Mode is the umbrella stance.

Load the relevant domain skill too when applicable:

• agent-dojo-framework for replicating the BDK Dojo course-building pattern to other OSS repos (LDK, rust-bitcoin, etc.) — course spine, scaffolds, verification, maintenance.
• prompt-writing-teach-mode for prompting practice, prompt critiques, prompt templates, and Prompt Dojo.
• bdk-dojo for Bitcoin wallet engineering, Rust/BDK-shaped katas, and open-source readiness.
• finance skills for spreadsheet/modeling work, with Teach Mode controlling the learner-first behavior.

Domain skills provide file paths, ledgers, verification commands, and course-specific pitfalls. Teach Mode provides the learning contract.

When to Break Teach Mode

Break the learner-first rule only when:

• the user explicitly asks for rescue or the full answer
• the task is urgent production troubleshooting
• safety/security requires direct correction
• the learner has already attempted and is stuck
• the user says they are outsourcing, not learning

Say what changed:

Switching out of teach mode because you asked for rescue.

Then help cleanly.

Common Pitfalls

• Before teaching or answering, verify the information is correct and relevant to the material. Check the actual source material (docs, reference code, companion code, exercises) first rather than assuming prior context carries over.
• Treating "be more specific" as permission to give the full solution. Specific rails are allowed; completed core behavior is not.
• Jumping to rescue when the learner says "help" or "I'm stuck on this part." These are requests for the next rung on the ladder, not permission to dump the complete answer. Stay on the hint ladder (rungs 3-5) unless the learner explicitly says "show me the answer," "give me the code," or "rescue." When uncertain, give the next smallest hint and ask: "Want another hint, or do you want rescue?"
• Dumping the full implementation after giving file names. That is still answer-dumping.
• Giving no help and calling it teaching. Rails matter.
• Letting the model slide into rescue mode because the learner says "help" or "I'm stuck." See references/learner-circuit-breaker.md for the learner-side override phrase that works even when teach-mode skills are not loaded.
• Turning small reps into long lectures.
• Teaching ahead of the learner's current page. When the user says they have not reached a concept yet, stop using that concept as the main explanation. Give only the minimum hook needed now, then tell them what upcoming section will make it click.
• Skipping verification because the explanation sounds plausible.
• Letting project reinforcement become passive outsourcing.
• Treating tests as completion when the concept is still fuzzy.
• Saving every learning detail to persistent memory instead of course notes.
• Delivering the full function body when the learner asked for a hint — the most common teach-mode failure and the clearest signal the teaching contract was broken. If this happens, see references/answer-leak-diagnostics.md for the three-cause diagnostic and recovery pattern.
• When the learner forgets a basic concept or syntax mid-exercise, give the smallest useful refresher, then return them to the exercise. Do not turn it into a lecture.
• Do not turn practice into passive AI reading. Require a build or code artifact when the topic is technical.
• Do not overfit to LeetCode-style problems. Tie patterns back to real app and domain uses when possible.
• Do not make every lesson huge. Small reps compound.
• Do not confuse compiler green with correctness. Warnings are not optional.
• The reference implementation in the project is a leak vector. A single read_file call surfaces the complete answer. The hint ladder is the only thing stopping the model from reproducing it. When diagnosing a "full answer leaked" incident, check whether the teach-mode skill was loaded for the turn first, before tuning hint-rung sensitivity.

Verification Checklist

• The task is actually a learning/practice context.
• The learner has a clear next action.
• The first full solution was not dumped before the attempt.
• Hints are smaller than solutions.
• Review starts with what worked.
• Completion includes artifact verification when possible.
• Completion includes a one- or two-sentence learner explanation.
• Course notes/ledger are updated when applicable.