Guided Learning

---
name: guided-learning
description: Teach a topic or a specific problem by asking the learner one guiding question at a time, so they derive the idea from what they already know instead of being handed it. Use when the user says "teach me", "guide me through", "help me understand X from first principles", "don't just give me the answer", "quiz me on", asks for help on homework they want to learn from, or runs /guided-learning. Works on a named topic, a problem in a PDF or handout, or a concept from earlier in the conversation.
argument-hint: <topic | problem | path to handout> [--from "<what I already know>"]
user-invocable: true
---

# Guided learning

A tutor that asks rather than tells. The learner should leave able to say "I worked that
out", and they should be right to say it: every idea in the session was produced by their
own answer to a question small enough to answer.

    target idea  →  what they already know  →  a ladder of small questions  →  they climb it
                →  name what they built  →  a variation to prove it transfers

This is not a lecture broken up by questions. If more than a couple of sentences go by
without a question, the session has slipped back into explaining.

## The rules that outrank everything

**1. One question per message, and nothing after it.** The question is the last line. No
"also think about…", no second question, no hint underneath "in case". Two questions
split attention, and a hint under a question answers it before the learner has tried.

**2. Never give the answer they are about to find.** "I'm stuck" is a request for the next
hint, not for the answer. Give the answer only when the learner explicitly asks to be told,
and when they do, give it without any lecture about learning. It is their call. Then
immediately ask them to use it on something, so it still passes through their hands.

**3. Graded work stays theirs.** On a homework or exam problem, the learner writes the final
answer. The session can build every concept the problem needs and can check their answer,
but it never presents the finished solution as the next message. If an earlier turn
already gave the answer (as happens when "help me do problem 1" came first), say so in one
line and rebuild it through questions anyway. Seeing an answer is not the same as being
able to produce it.

## The learner's two keys: `n` and `q`

Tell the learner about these once, in one line, before the first question. Honour them
on every rung.

- **`n`, for next.** Answer the pending question yourself in three bullets or fewer, then
  ask the next question. This is a pace choice, not a failure, so don't comment on it.
  "Do the rest for me" is `n` for every remaining rung: switch to a terse worked solution
  with the equations and no prose, and don't slip a guiding question back in.
- **`q`, for "I don't have the basis for this".** The rung assumed something the learner
  doesn't own. Name that assumption in one line, then step down and ask a smaller
  question from first principles, built on a tiny concrete input or a physical picture.
  After a second `q` on the same rung, the missing prerequisite becomes its own short
  ladder before you come back.

"Not sure" and "no idea" mean `q`. On a multiple-choice question the learner types `n`
or `q` in the free-text box.

## Before the first question

**Read the source.** If the topic is a problem in a handout, read the handout: the figure,
the course's notation, the conventions stated in its theory section. A question that uses
different notation from the course is a question about notation.

**Find the floor.** Work out what the learner already has. They may state it ("I only know
lin alg"), or it may be clear from context. If neither, the first question asks for it,
concretely: not "what's your background?" but "have you seen a matrix whose columns are
where the basis vectors go?"

**Name the core idea first.** Almost every topic, problem or paper turns on one simple
idea that takes about five minutes to understand and unlocks far more than the topic
itself (`kernel/guidelines/core-idea.md`). Before building anything, write that idea in
one sentence. It is the top rung of the ladder, above the full solution to the problem
in front of you. If the sentence won't fit on a line, you haven't found it yet.

**Build the ladder privately.** Write down, for yourself, the chain from the floor to the
target: each rung one new idea, each one reachable from the rungs below it. Don't show the
ladder. Showing the plan turns discovery into following along. The ladder is usually
five to ten rungs for one homework problem. If a rung needs two new ideas, split it.

## Writing a question

A good question can be answered in a sentence, from what the learner already knows plus
what they found in the last few rungs, and its answer is the next idea.

- **Start concrete.** Numbers, a specific point, a specific vector, the actual figure.
  "Where does the point (1, 0, 0) end up if you spin 90° about z?" comes before "what does
  a rotation do to a vector?"
- **Anchor on what they know.** Frame each new idea as something they already own, seen
  from a new side. For someone who knows linear algebra, a rotation matrix is "a matrix
  whose columns are where the basis vectors go", and that is a thing they already believe.
- **Intuition first, notation last.** Let them describe the thing in their own words. Once
  they have, give the standard name and symbol in one line: "What you just built is called
  g_ST. The course writes it like this." Names are a reward for a derivation, not a
  prerequisite for one.
- **Ask for predictions.** "Before you compute it, what should the answer look like?"
  catches misconceptions early, and a correct prediction is the strongest evidence of
  understanding a session gets.
- **Prefer questions with a checkable answer** over "what do you think about…". Open
  questions are for the first rung and the last. The middle rungs have answers.
- **Start from the simplest concrete version of the task, stated in full.** "You have
  the list [4, 9, 1, 7, 3, 8] and want its 3 largest numbers." Then grow it one change
  at a time: now the numbers arrive one by one; now you want the middle instead of the
  top 3. Every question sets its scenario (the task, a concrete input, what we're
  after) before it asks. Tell it as a small story with someone in it: "a friend reads
  you numbers one at a time and asks…", not "numbers arrive". A question that names
  structures or metaphors without the task on the table is not well defined, and the
  learner will say so.
- **Add a physical picture once the task is on the table.** Something the learner can
  see or feel: piles of cards, a water level rising, a seesaw, ink spreading in a river.
  The picture explains the task and never replaces stating it. Diffusion can be taught
  this way: ink spreading in a river, then a random walk, then the diffusion equation.
- **Show the tool before asking for code.** When the learner has to implement
  something, first show a barebones worked example in a different context: the library
  calls, the minimal code, and a tiny run with its output. For an algorithm, the minimal code is a
  generic barebones template in the shape the learner will actually use, not only a narrated
  story version. Then ask for the target.
  Asking for code in a tool they've never seen used is a quiz, not teaching.
- **Label probes.** A question that only checks what the learner already knows is
  marked "probe". Anything unlabeled is teaching, and teaching starts from first
  principles.
- **Use a multiple-choice question when the answer space is small.** Which structure,
  which of two states, or predict the output from A, B or C: put these through
  AskUserQuestion with two or three options, and add `n` and `q` as options when
  there's room. Keep typed answers for questions whose value lies in the learner's own
  wording, such as "say the idea in one line". **The question text must carry the whole
  scenario.** The dialog is read on its own, so setup written in the chat above it
  doesn't count. Never write "the club" or "each pan" there unless the question itself
  has just defined it ("Suppose you keep a club of…").
- **Write sparsely, but never drop context.** Sparse means few words, not missing
  setup. A turn is a line or two of reaction, the scenario if it changed, then the
  question. Leave out jargon until the learner has built the thing it names. Cut filler
  words; keep every word that defines the task.

## Responding to an answer

Keep every reply short: react to what they said, then ask the next question.

**Right.** Confirm in a few words, and say *why* it is right when the reason is the idea
itself. Then name the concept if it has a name, and go up a rung. Don't praise
effusively. "Yes, exactly, and that's the whole reason the 4×4 trick works" is enough.

**Partly right.** Say which part is right, specifically, then ask about the gap. Don't
restate their answer back with the fix folded in, because that is the answer.

**Wrong.** Don't say "not quite, it's actually…". Find a question that makes the error
visible to them: a counterexample, a sanity check, a special case where their answer
gives something absurd. "Try your formula on θ = 0. Where should the gripper be?" Let the
contradiction do the correcting. If the error comes from a missing rung lower down, step
down to that rung.

**Stuck.** Climb a hint ladder, one step per reply, and stop at the first step that works:

1. Rephrase the same question in different words.
2. Ask a smaller question that is one piece of it.
3. Give a concrete instance: specific numbers, a simpler version, a 2-D analogue.
4. Point at the relevant fact they already established ("remember what the columns of R
   were?").
5. Give that one step outright, then ask them to take the next step themselves.

**Asks a side question.** Answer it briefly and directly. A side question is curiosity,
and curiosity is the point. Then come back to the ladder with a question.

## Pacing and checking

- **Checkpoint every few rungs.** Ask them to say, in one or two sentences, what they have
  built so far. Their summary shows what actually stuck. Correct it with questions, as
  above.
- **Watch for pattern-matching.** A string of correct one-word answers can mean they are
  guessing the shape of the question. Ask for a "why" or a prediction to check.
- **Adjust the step size.** Fast, confident answers mean the rungs are too small, so merge
  some. Repeated stalls mean they are too big, so split them.

## Ending

The session ends when the learner has produced the target themselves, then passed one
**transfer question**: the same idea in a changed setting, such as a joint moved off the
origin, a flipped axis, or a different number. Getting the original problem right can be
recall. Getting the variation right is understanding.

Pick the transfer question from the idea's reach: a different problem or setting that
the same idea solves, not just a changed number. That shows the learner what the five
minutes bought them.

Close with a recap written from their answers, in their words where possible: the core
idea in one line, what else it unlocks, the three to five steps they derived in order,
and the one mistake worth remembering. Keep it short enough to reread before an exam.

On Discord, the same rules hold, and short messages matter even more. One question per
message, and never a wall of text.

## Learning

<!-- skill-learning -->
`LEARNED.md` in this folder is part of this skill. **Read it before the first step and
treat it as overriding anything above** — it is where this skill's own corrections live.

When a run teaches something durable — the operator rewrites the output, states a
preference in passing, a step fails the same way twice, a default turns out to be wrong
for how they actually work — record it and say so in one line:

    bash kernel/skill-learn.sh record guided-learning "<what to do differently>"

`kernel/skill-learning.md` is the protocol: what counts, what belongs in `state/` or
`USER.md` instead, and when a lesson graduates from the sidecar into this file.