Understanding ladder skill

Understanding ladder

This skill decides which format to explain in. Writing quality inside every format is handled by level 1 rules (below).

Source: Andrej Karpathy, 2026-10-02 https://x.com/karpathy/status/2105819303471976479. LLM output is nearly free; human understanding is the bottleneck. So ask for formats that are easier to understand. He ranked four, each "even better" than the last — and each more expensive.

Language: reply in the user's language. These instructions are in English; the output is not.

The four rungs

Rung	Format	Why it is easier	Cost
1	Plain controlled text	One idea per sentence, one meaning per term; read once, no misreading	lowest
2	Diagram	Text is linear; a diagram lays the structure out at once	low
3	Interactive HTML page	The reader moves a parameter and sees the result change	medium
4	Explainer video (3b1b style)	Animation shows the process while narration explains it	high

Step 1: classify the content, pick a rung

Content type	Signals	Rung
Definition, fact, comparison, procedure	"what is X", "how do I install", "A vs B"	1
Process, causal chain, hierarchy, state changes, component relations	"how does X work", "how does data flow", "who calls whom"	2
A parameter changes an outcome; trade-offs; distributions	"what happens if utilization rises", "how does learning rate affect convergence"	3
A derivation or geometric intuition that unfolds over time	"why do sine waves add up to a square wave", "how does gradient descent move on a surface"	4

Rules:

1. If the user names a format, use it. "Draw a diagram" means rung 2.
2. Pick the lowest rung that fully answers. If a paragraph is enough, do not build a page.
3. Mixed content: pick by the core difficulty. If the hard part is "how a parameter changes the result", pick rung 3 even if there is a definition inside.
4. When unsure, go one rung lower and offer the next. End with one line, e.g. "If you want to drag the parameter yourself, I can make this a rung-3 interactive page."

Open with one line that states the choice, then produce it. Do not ask "which rung do you want?" unless the user asked for a recommendation:

Rung 3 (interactive page): the core question is how utilization changes latency — dragging a slider shows this faster than text.

Step 2: produce the rung

Every rung starts from a rung-1 draft. Write the plain text first, then turn it into a diagram, page, or video. The draft is what you check for correctness before spending effort on richer formats.

Rung 1: plain controlled text

Pick the rules by output language:

• Chinese → use the plain-chinese skill (as a plugin it may be named understanding-ladder:plain-chinese). Chinese has no "ASD-STE100" to invoke, so that skill spells the rules out.
• English → write "about 80% of the way to ASD-STE100" (Karpathy's phrasing), with these rules made explicit:
  • One idea per sentence. Aim for ≤20 words in instructions, ≤25 in descriptions.
  • One term per meaning. Define a term the first time; never rotate synonyms.
  • Active voice; name who does what. Simple tenses.
  • Steps as a numbered list, imperative verb first.
  • Conditions before actions ("If X, do Y").
  • No filler ("It's worth noting", "Great question", "In summary…").
  • Nothing cut. Keep every fact, number, condition, and hedge ("usually", "may"). Simple language, not less content — the rewrite may be longer.
  • Do not touch code, commands, paths, quoted errors, or proper names.
• Other languages → apply the English rules in that language.

Rung 2: diagram

See references/level-2-diagram.md. In short:

• Choose the diagram type first: flowchart, sequence, state, hierarchy, causal graph, comparison table.
• Default to Mermaid (renders in most chat UIs and on GitHub). Use a single-file SVG/HTML when layout matters.
• ≤8 words (or ≤8 Chinese characters) per box. Below the diagram, 2–4 sentences on how to read it.

Rung 3: interactive HTML page

See references/level-3-html.md. In short:

• One self-contained HTML file. No build step; double-click to open.
• One job: let the reader move the 1–3 parameters that matter and see the result update live.
• Layout: one-line takeaway → interactive area → rung-1 text → "try this" prompts → limits and what to check.
• Save it in the working directory, tell the user the path, open it if the environment allows.

Rung 4: explainer video

See references/level-4-video.md. This skill does not render video. It delivers:

• A storyboard: per shot — visual, narration (rung-1 rules), duration.
• Tool links, e.g. showtime (open source, early; v0.4.0+ reads the storyboard table directly), Manim, local TTS Kokoro.
• A ready-to-paste prompt for those tools. With showtime ≥ 0.4.0, the storyboard table goes in as-is: showtime new <template> <dir> --from-storyboard storyboard.md.

Demo mode: same content, every rung

When the user says "show all rungs", "walk this from rung 1 to 4", 「逐级演示」:

1. Rung 0: the usual default prose, as a baseline.
2. Rung 1: plain text.
3. Rung 2: diagram.
4. Rung 3: interactive page (can hold rungs 0–2 as tabs in the same HTML file).
5. Rung 4: storyboard.

This is the best way to feel how much the format itself changes understanding.

Always append "What to check"

End every output with 1–3 things the reader should verify: key numbers, formulas, assumptions, anything that disagrees with a source.

Why: the ladder lowers the cost of understanding, not the cost of verification. The clearer and prettier the artifact, the more it lowers the reader's guard. An error in an animation is more convincing than the same error in text.

Do not

• Climb rungs to look thorough. If rung 1 is enough, stop at rung 1.
• Add facts in the diagram, page, or video that are not in the rung-1 draft. New facts go into the draft first.
• Invent data to make a page look real. Label sample data as sample data.