skills/concept-rediscovery-walk/SKILL.md
Guides a learner to invent a math or ML concept themselves through a Socratic walk — a sequence of small guessable questions that ends with the learner stating the formal definition unprompted. The 3Blue1Brown signature move. Use when the learner is meeting a foundational concept (eigenvectors, gradient, attention, softmax, KL divergence) for the first time, when prior exposure produced memorization without understanding, or when the user says "explain it from scratch", "I want to really get it", "build it up for me", or "where does this come from".
npx skillsauth add lyndonkl/claude concept-rediscovery-walkInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
The principle is simple: a learner who guesses the equation Av = λv from "what would survive a transformation unchanged?" owns eigenvectors in a way that no exposition can match. This skill structures the walk that makes that guess possible.
Quick example (Eigenvectors):
Set the seed: "Picture any 2D matrix as a transformation that bends the plane — most arrows get rotated and stretched. But are there special arrows that only get stretched, not rotated?"
Let them guess: "What would such an arrow satisfy, if A is the matrix?" Learner: "Av is parallel to v?"
Tighten: "Right — and 'parallel' means equal up to a scalar. So we need…?" Learner: "Av = λv for some number λ."
Name what they invented: "You just wrote the eigenvector equation. v is an eigenvector, λ is its eigenvalue. Now we never have to introduce them — you derived them."
Ten lines. The learner did most of the talking. That is the move.
Copy this checklist and track your progress:
Rediscovery Walk Progress:
- [ ] Step 1: Identify the concept and its motivating question
- [ ] Step 2: Choose the seed observation (the door)
- [ ] Step 3: Plan the question ladder (3-5 rungs to the definition)
- [ ] Step 4: Walk the learner up the ladder, one guess at a time
- [ ] Step 5: Name what they invented; restate it cleanly
- [ ] Step 6: Verify ownership with a small unfamiliar question
Step 1: Identify the concept and its motivating question
Every concept exists because it answers a question. Before walking, pin down what the question is. Eigenvectors answer "which directions does this transformation leave alone?" Gradient answers "which way is uphill steepest?" Softmax answers "how do I turn arbitrary scores into a probability distribution?" If you cannot state the motivating question in one sentence, you have not understood the concept well enough to walk anyone to it.
For a catalog of motivating questions per concept, see resources/examples.md.
Step 2: Choose the seed observation (the door)
The seed is a concrete observation or scenario that makes the motivating question feel natural. Three good seed types:
Pick the seed that requires the least background to grasp. Bad seeds open with formalism ("Let A be a square matrix over ℝ…"); good seeds open with a picture or a problem.
Step 3: Plan the question ladder (3-5 rungs to the definition)
Sketch the ladder before you start walking. Each rung is a question the learner can answer with what they already know plus the seed. The last rung's answer is the formal concept.
A good ladder has these properties:
For ladder templates by concept, see resources/examples.md. For ladder design heuristics, see resources/methodology.md.
Step 4: Walk the learner up the ladder, one guess at a time
Ask the rung. Wait for the answer. If the answer is right, name it cleanly and ask the next rung. If the answer is partial, affirm what's right and probe the gap ("Yes — and what about the other direction?"). If the answer is wrong, do not correct — probe: "What made you think that? Let's test it on a tiny example."
The ratio matters: aim for the learner to type more than you do during this phase. If you find yourself writing paragraphs while waiting, your rung was too vague — break it smaller.
Step 5: Name what they invented; restate it cleanly
After the last rung, do this in two beats:
This is the only moment the formal definition appears. It appears at the end, as a compression of what the learner already understands. Sanderson's principle, applied: definitions are the ending point, not the start.
Step 6: Verify ownership with a small unfamiliar question
Ownership ≠ recognition. Test with a question they haven't been walked through:
Answers reveal whether the picture stuck. A learner who sees the rotation case has no real eigenvectors because no real direction is left unrotated has the picture. A learner who says "I'd have to compute the characteristic polynomial" has memorization, not understanding — back to Step 4 with a different angle.
If a walk is dragging, almost always one of these cuts will fix it.
Cut 1: Cut the setup. If your seed needs more than two sentences to land, the seed is wrong. Pick a more concrete one.
Cut 2: Cut the lecture. If you find yourself explaining for more than three sentences before the next question, you've stopped walking and started telling. Break it into a question.
Cut 3: Cut the rung count. If you planned 7 rungs, half of them are filler. The walk usually wants 3-5. More rungs = more places for the learner to lose the thread.
The walk uses four kinds of questions; rotate them.
1. Picture-prompts (lowest friction, use early)
2. Goal-prompts (set up the search)
3. Test-prompts (force concreteness)
4. Anomaly-prompts (productive surprise)
If a learner stalls on one type, switch to another. Picture-prompts unstick most stalls.
Used for: eigenvectors, gradient, dot product, softmax, cross-entropy, Jacobian. Structure: seed → 3-5 rungs → name → verify. Length: ~10 exchanges, ~5 minutes.
Used for: attention (Q, K, V — 3 sub-walks fused), backprop (chain rule + reverse mode), PCA (covariance + eigenstuff). Structure: walk to each sub-concept separately, then a final rung that fuses them. Length: ~25 exchanges, ~15 minutes.
Used for: high-dim phenomena (concentration of measure), counterintuitive results (KL asymmetry). Structure: present the anomaly → "guess why" → walk through the intuition repair. Length: ~10 exchanges.
For one full walked example per pattern, see resources/examples.md.
| Concept | Seed | Final rung | |---|---|---| | Eigenvectors | "Most arrows get rotated and stretched. Are there ones that only get stretched?" | "Av = λv" | | Gradient | "On a hilly surface, you want to climb fastest. Which way?" | "The vector of partial derivatives" | | Dot product | "When are two vectors 'similar'?" | "a·b = |a||b|cos θ" | | Softmax | "Turn arbitrary scores into a probability distribution." | "exp(xᵢ)/Σexp(xⱼ)" | | Attention Q | "Each token needs to ask the others for info. What does 'asking' look like as a vector?" | "The query vector" | | Cross-entropy | "How do we measure how 'wrong' a predicted distribution is?" | "−Σpᵢ log qᵢ" | | Jacobian | "Derivative is a number for f: ℝ→ℝ. What is it for f: ℝⁿ→ℝᵐ?" | "The matrix of partial derivatives" |
For full walked dialogues per concept, see resources/examples.md.
For the deeper methodology behind seed selection and rung sizing, see resources/methodology.md.
testing
--- name: advisory-edit description: A strict advisory-only editing discipline for a writer who dictates ("speaks out") essays and wants help WITHOUT having their voice changed. The editor directs structure, flags grammar, and suggests strategic language — but never modifies the writer's text unless the writer explicitly says "apply" / "make that change" / "rewrite this." Produces a line-referenced, suggestion-only critique where every item is marked the writer's call. Four passes: structural, l
testing
Provides the house style for analyst-grade strategist writing — third-person register with sparing first-person, no em dashes, no "not X, not Y, not Z" negation cascades, numbered footnote citations rather than inline source parentheticals, specific opinion-signaling phrases, and topic-forward paragraph structure modeled on voice patterns observed in Damodaran's Musings on Markets and Thompson's Stratechery. Use when consolidating working notes into a finished long-form strategist or analyst report that must read as written by a senior human analyst rather than an AI assistant.
testing
Renders a markdown report to a PDF using pandoc with xelatex (11pt serif body, 1-inch margins, numbered footnotes, formal heading hierarchy). Requires a one-time install of pandoc and a LaTeX engine on the user's machine — basictex on macOS or texlive-xetex on Linux. Does not attempt automatic install. Fails loudly with the exact install commands if pandoc or xelatex is missing on the user's PATH. Use when producing a finished strategist or analyst report PDF from a polished markdown source.
testing
Produces step-by-step computational walkthroughs of vector and matrix operations as a sequence of numbered "frames", showing the explicit state at each step. The text-equivalent of a 3Blue1Brown animation — each frame shows what changed and why, so the learner can re-trace the operation by hand. Use when the learner needs to *see* a computation unfold (eigenvalue computation, attention with 3 tokens, gradient descent step, SVD on a 2×2, layer norm on a 3-vector, softmax of a small input), when an explanation has been given but the learner needs to ground it in a worked example, or when introducing an operation that's intimidating in symbol form but trivial in pencil-and-paper form.