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
Cluster a conference's event records into a small set of coarse themes with finer sub-clusters, an explicit outlier bucket, and soft (multi-membership) affinities — using the hybrid embed-then-label pipeline (embed abstracts, reduce, density-cluster, then LLM-label the clusters) when embedding libraries are available, and an LLM-reasoned hierarchical fallback when they are not. Embeddings do the grouping; the LLM only names the groups. Conference-agnostic. Use when turning structured event records into a navigable theme map for preference elicitation and scheduling, when you need 6-8 reasonable themes rather than 20 muddy ones, or when overlapping talks must belong to more than one theme. Trigger keywords - theme clustering, cluster talks, embed then label, soft membership, outlier talks, conference themes, topic map.
development
Build a personal conference schedule as a constraint-optimization problem — hard constraints (no time overlap, room-to-room travel time, capacity/registration, the attendee's own must-attends and blackouts) plus a user-owned weighted objective trading interest against breadth, pacing (maximize contiguous free time), and serendipity. Surfaces unbreakable conflicts (two high-value overlapping talks the model cannot rank) as decisions for the human rather than silently picking, and reports what each choice traded away. Conference-agnostic. Use to turn a preference profile plus a theme map into a day-by-day plan, to resolve overlapping sessions, or to balance a packed vs paced schedule. Trigger keywords - schedule optimization, conference schedule, constraint optimization, overlapping talks, contiguous free time, conflict surfacing, packed vs paced.
development
Parse a heterogeneous conference program (markdown, HTML, PDF-derived text, or JSON) into normalized event records with per-field confidence scores and independent classification axes (topic, depth, format, prerequisites, recorded, capacity). Detects the program's format before extracting, treats every inferred field as uncertain (present vs inferred vs missing), and flags thin or missing abstracts so downstream enrichment can target them. Conference-agnostic. Use when ingesting a conference or event schedule into a structured store, normalizing a talk/session list, or extracting per-session metadata with calibrated confidence. Trigger keywords - program ingestion, parse schedule, session extraction, event records, conference program, talk metadata, per-field confidence.
development
Build a personalized preference profile from a small number of well-chosen, cluster-grounded questions instead of a long survey. Represents the person's interests as an uncertainty region over the theme map, picks the single highest-information-gain choice-based question (contrasting real talks from different clusters), balances exploiting known interests against exploring uncertain ones, deliberately injects outlier probes to fight selection bias, and stops as soon as the schedule would be stable. Also elicits the user-owned objective weights and hard constraints. Interactive — runs where it can actually ask the person. Conference-agnostic. Use to turn a theme map into a preference profile, to decide what to ask a conference attendee, or to elicit scheduling priorities. Trigger keywords - preference elicitation, ask few questions, information gain, choice-based questions, selection bias probe, objective weights, attendee preferences.