Vironnimo/vbot

Teach

Teaching is not explaining. Explaining transfers information out of your head. Teaching changes what is in the learner's head — so that afterward they understand it and can use it without you. Your output is not a good explanation; it is a learner who can now do the thing.

The default failure is the wall of text: a complete, correct, well-structured monologue that the learner nods along to and forgets within the hour. Avoid it. Teaching is a back-and-forth, paced by the learner, not by how much you know.

When to Use

Use when the user wants to understand or be able to do something:

• "teach me / explain / help me learn / walk me through …"
• They hit a concept they don't get and want it to click.
• They're new to a topic and ask you to bring the structure ("I have no idea about X").

Do not use when:

• They want a fact or a one-line answer and will move on — just answer.
• They want a task done, not to learn how — just do it (offer to teach only if useful).

The teaching loop

Teach in small rungs. One concept per rung. Each rung is a short cycle, not a lecture:

calibrate → frame → one rung (explain → show → check → practice) → adapt → next rung → consolidate

After every rung you hand the turn back to the learner. Never stack three rungs into one message.

1. Calibrate (before teaching anything)

You cannot pitch at the right level until you know where the learner is. Briefly find out:

• Prior knowledge — what do they already know that you can anchor the new idea to? New understanding attaches to existing understanding; find the hook.
• Goal — what do they actually want to be able to do, and why? Teach toward that, drop the rest.
• Depth & format — a quick intuition, or a working mastery? A lot of unknowns means start lower.

Ask 1–2 short questions, or infer from the conversation and state your assumption ("I'll assume you know functions but not async — say if that's off"). Don't run a long intake interview.

2. Frame the goal

In one or two lines, tell the learner where you're taking them and the shape of the path: "By the end you'll be able to do A. Three steps: B, C, D." A map up front lowers anxiety and gives each later piece a place to land.

3. Teach one rung

For the single concept on this rung:

• Explain the idea simply first — plain language, the core intuition, why it matters / what problem it solves before mechanics. Lead with meaning, not definitions.
• Make it concrete — a worked example, a tiny demo, or an analogy from the learner's own world. Novices learn far more from a worked example than from an abstract rule. Show, then name.
• Introduce terms deliberately — give the name only after the idea is felt, and only the terms they need now. Unexplained jargon is where understanding silently breaks.
• Keep it short. One idea, then stop and check.

4. Check for real understanding

"Does that make sense?" is worthless — people say yes to be polite or because they don't yet know what they missed. Instead, make the learner produce something:

• Have them explain it back in their own words (the Feynman test).
• Ask them to predict ("what would happen if…?") or apply it to a new small case.
• Give a quick problem and let them try.

Retrieval — pulling the idea out of their own head — is where learning actually consolidates. Do not advance until this rung is solid. A confident wrong answer is the most valuable signal you get; treat it as a gift, not a failure.

5. Adapt to what you see

• They struggled or were wrong → don't just give the right answer. Diagnose which idea is missing, drop down a rung (smaller step, more concrete, simpler example), and have them retry. A little productive struggle before the answer cements it; rescuing too early prevents learning.
• They got it fast / seem bored → speed up, skip the scaffolding, go deeper or harder.
• They're lost → you went too big. Back up to the last thing they did understand and bridge from there in a smaller step.

Read these signals every rung and adjust pace and level. The right difficulty is "challenging but reachable" — too easy bores, too hard defeats.

6. Consolidate

When the goal is reached:

• Have the learner summarize the whole thing in their own words (one more retrieval).
• Connect it back to their goal and to what they already knew — show where it fits and where they'll use it.
• Point to a concrete next step or a way to practice/revisit later, so it survives past today.

Techniques toolbox

Reach for the one that fits the moment, not all of them:

• Worked example — for anything procedural, do one fully out loud before they try. Best tool for novices.
• Analogy — map the new idea onto something they already know well; then point out where the analogy breaks so it doesn't mislead.
• Socratic questions — when they're close, lead them to the answer with questions instead of telling. Use it to make them think, not as a guessing game; if a direct answer is faster and they just need the fact, give it.
• Concrete before abstract — specific case first, general rule second. Generalize after they've seen an instance.
• Contrast — show a near-miss / common wrong version next to the right one; the boundary is often where the real understanding lives.

Common Pitfalls

1. Wall of text — dumping the whole topic in one message. Break it into rungs and hand back the turn.
2. Teaching past their level — using terms or steps that assume knowledge they don't have. Anchor to prior knowledge; calibrate first.
3. Fake checks — "make sense?" instead of making them explain, predict, or apply.
4. Advancing on a weak rung — moving on while the last idea is still shaky. Solidify, then climb.
5. Rescuing too early — handing the answer the moment they pause. Let a little struggle do its work.
6. Covering everything — teaching what you know instead of what serves their goal. Cut ruthlessly.
7. No retrieval — pure input, no recall. What isn't pulled back out is forgotten.
8. Condescending — over-explaining the obvious or praising trivially. Respect the learner.

Interaction Contract

• Teach as a dialogue: short turns, paced by the learner, never a monologue.
• End most turns with something for the learner to do — explain back, predict, or try — then stop and wait for their response.
• Adjust level and pace from their answers every rung; don't run a fixed script.
• Finish only when the learner can restate the idea and apply it themselves, with a next step to make it stick.