worked-example-walkthrough

What this skill does

# Worked Example Walkthrough

## Table of Contents
1. [Workflow](#workflow)
2. [Frame Anatomy](#frame-anatomy)
3. [Choosing the Right Example](#choosing-the-right-example)
4. [Common Patterns](#common-patterns)
5. [Guardrails](#guardrails)
6. [Quick Reference](#quick-reference)

A walkthrough is a sequence of numbered frames showing the state of a computation at each step. Each frame answers three questions: *what's the current state?*, *what operation produced it?*, and *what should the learner notice?*

This is the closest pure text gets to a 3Blue1Brown animation. The learner can re-trace the operation by hand, and the explicit intermediate states catch confusions that a final-result-only treatment hides.

**Quick example (Eigenvalues of a 2×2 matrix):**

> **Compute the eigenvalues of A = [[4, 1], [2, 3]].**
>
> **Frame 1.** State: A = [[4, 1], [2, 3]]. We want λ such that det(A − λI) = 0.
>
> **Frame 2.** Form A − λI:
> ```
> A - λI = [[4-λ,  1 ],
>          [ 2,  3-λ]]
> ```
>
> **Frame 3.** Compute the determinant:
> det = (4 − λ)(3 − λ) − 1·2 = (12 − 7λ + λ²) − 2 = λ² − 7λ + 10
>
> **Frame 4.** Solve λ² − 7λ + 10 = 0:
> Factor: (λ − 5)(λ − 2) = 0. So λ = 5 or λ = 2.
>
> **Frame 5.** Eigenvalues: 5 and 2. Quick sanity check: trace(A) = 4 + 3 = 7 = sum of eigenvalues ✓; det(A) = 12 − 2 = 10 = product of eigenvalues ✓.
>
> **What to notice:** The characteristic polynomial is just det(A − λI) expanded; finding eigenvalues is just root-finding. No magic.

Five frames, ~80 words. The learner can redo this on paper in under a minute.

## Workflow

Copy this checklist and track your progress:

```
Walkthrough Progress:
- [ ] Step 1: Pick the smallest possible example that exercises the concept
- [ ] Step 2: Write the goal — what we'll compute and why
- [ ] Step 3: Plan the frames (3-7 typically)
- [ ] Step 4: Write each frame: state, operation, notice
- [ ] Step 5: End with a sanity check or invitation to verify
- [ ] Step 6: Optional — invite the learner to redo with a variant
```

**Step 1: Pick the smallest possible example that exercises the concept**

The example must be *small*. 2×2 matrices, 3-vector inputs, 3-token sequences. Bigger examples obscure the structure with arithmetic.

The example must also *exercise* the concept — not just trivially demonstrate it. A diagonal matrix has trivial eigenvectors; pick a 2×2 that's not diagonal. A scalar attention is trivial; pick at least 3 tokens.

For a catalog of recommended example sizes per concept, see [resources/examples.md](resources/examples.md).

**Step 2: Write the goal — what we'll compute and why**

Single sentence. "Compute the eigenvalues of A = [[4, 1], [2, 3]]." or "Apply attention to a 3-token sequence with random Q, K, V vectors." The goal frames everything that follows.

**Step 3: Plan the frames (3-7 typically)**

Each frame is one operation. Sketch the frames before writing them out — this catches the "skipped step" problem before it hits the page.

A frame budget that works for most operations:
- 3 frames: trivial chain (one transformation)
- 5 frames: typical single-concept walkthrough (eigenvalues, softmax, single SGD step)
- 7 frames: compound walkthrough (attention with all sub-steps shown)

If you find yourself wanting >7 frames, either the example is too big (shrink) or the operation has multiple sub-operations that each deserve their own walkthrough.

**Step 4: Write each frame: state, operation, notice**

Each frame has three parts (see [Frame Anatomy](#frame-anatomy)):
- **State:** the current values, shown explicitly.
- **Operation:** what we just did to get here (or what we're about to do).
- **Notice:** one sentence pointing out something the learner might miss.

The "notice" is what distinguishes a walkthrough from a worked solution. A worked solution shows the steps; a walkthrough also says *what to look at*.

**Step 5: End with a sanity check or invitation to verify**

Every walkthrough ends with one of:
- A sanity check: "trace ✓, determinant ✓".
- A consistency check: "the result has the expected shape".
- An invitation: "try the same operation on A = [[1, 2], [3, 4]]; the answer should be λ ≈ −0.37 and λ ≈ 5.37."

The sanity check is what tells the learner the result is right. It also doubles as a *reusable verification trick* they can apply to similar problems.

**Step 6 (optional): Invite the learner to redo with a variant**

If the learner has time and the example is short, invite them to redo with a small change:
- "Same matrix, different starting vector: redo with v = (0, 1) instead of (1, 0)."
- "Same attention computation, but with one token's K replaced by zero: predict the change to the output before computing."

Variants check whether the *picture* transferred, not just the arithmetic.

## Frame Anatomy

Each frame has three parts. Keep them visually distinct.

```
**Frame N.** [Operation: short verb phrase, what we're doing.]
[State: explicit values, in a code block if needed.]
[Notice: one sentence — what to look at.]
```

### State block

Use a code block for matrices, vectors, and equations. Show actual numbers; resist the urge to leave things symbolic. The point is *concreteness*.

```
v = (3, 4)
|v| = √(3² + 4²) = √25 = 5
```

### Operation phrase

Short verb phrase: "Compute…", "Apply…", "Substitute…", "Solve…". One line.

### Notice sentence

One sentence pointing at the most important feature of this frame.
- "The cross terms cancelled — that's because A is symmetric."
- "Notice the second eigenvalue is negative — A reflects along that direction."
- "The softmax peaked on the first row — token 1's query strongly matched key 1."

If a frame doesn't earn a notice sentence, it might not need to be its own frame. Consider merging.

## Choosing the Right Example

The example you choose makes or breaks the walkthrough. Heuristics for choosing:

### Use specific small numbers, not symbols
A walkthrough with `a, b, c, d` is a *derivation*, not a walkthrough. Pick numbers like 2, 3, 1, −1 — small enough to compute by eye, varied enough to expose pattern.

### Avoid the simplest possible case
Identity matrix, zero vector, all-equal scores — these are *too* trivial; they don't exercise the operation. The walkthrough learner needs to see what happens when the operation is *non-trivially active*.

### Pick examples with verifiable properties
Symmetric matrices have real eigenvalues — easy to spot a bug. Stochastic matrices have a stationary distribution — easy to verify. Pick examples with these checkable properties so Step 5's sanity check is meaningful.

### When in doubt, use the smallest non-trivial size
- Matrices: 2×2 first; 3×3 only if 2×2 doesn't exercise the concept.
- Vectors: 2D or 3D.
- Sequences: 3 tokens minimum (so attention is interesting), 4 if you need parity.
- Networks: 1-layer, 2-input, 1-output minimum (for backprop demos).

For a recommended example per concept, see [resources/examples.md](resources/examples.md).

## Common Patterns

### Pattern A: Single computation walkthrough
Used for one-shot operations: eigenvalue compute, single SGD step, single attention forward pass, softmax of a vector.
Length: 3-5 frames.
Closing: sanity check.

### Pattern B: Iterative walkthrough
Used for processes that loop: gradient descent over multiple steps, power iteration finding eigenvectors, diffusion sampling.
Length: 5-7 frames showing 2-3 iterations explicitly, then "and so on…".
Closing: convergence comment + invitation to predict the limit.

### Pattern C: Comparative walkthrough
Used to show the *contrast* between two operations: matrix-vector mul as row-dot vs as column-combination; layer norm vs batch norm; SGD vs Adam on the same gradient.
Length: parallel frames in two columns or two passes.
Closing: bridge sentence on what makes them equivalent or different.

For one filled walkthrough per pattern, see [resources/examples.md](resources/examples.md).

## Guardrails

- **Show actual numbers, not symbols.** A walkthrough with `Av` is