Static hubs for animation & FX experiments

Explainer

Understanding Ladder

Output formats when agents do the legwork

Models will do more building. Your job moves up to oversight: read what they produced, spot mistakes, and decide. The format you ask for changes how fast that work goes. Andrej Karpathy sketched a ladder on 2 October 2026: each rung helps understanding more than the last, from simplified prose through diagrams and HTML to bespoke explainer video. This page turns that ladder into a pick list for Crank experiments. No figures from the post are quoted here.

The understanding ladder: four output formats, bottom to top A ladder with four rungs, read from the ground up. Rung 1, simplified English near ASD-STE100: use for chat answers, bot reports and anything Peter must read quickly; effort low. Rung 2, diagrams and images: use when the point is structure, flow or comparison; effort low to medium. Rung 3, self-contained HTML pages: use when the reader should scan, click or try something; effort medium. Rung 4, bespoke explainer video: use when order in time is the point and a still page cannot show it; effort high. An arrow on the right says higher rungs cost more human time to request and review, but can save time when the topic is hard. READ BOTTOM TO TOP · EACH RUNG HELPS MORE RUNG 1Simplified English (~80% STE)When: quick reads, reports, chat handoffsEffort: low RUNG 2Diagrams and imagesWhen: flows, maps, before/after shapesEffort: low to medium RUNG 3Self-contained HTMLWhen: scan lists, try controls, one shareable URLEffort: medium RUNG 4Bespoke explainer videoWhen: sequence in time is the pointEffort: high more help · more build effort
The understanding ladder. Start on the lowest rung that still works. Climb when the reader is stuck or the topic is dense.
  1. Rung 1 Can plain words carry it? 1 ~80% STE
  2. Rung 2 Is the shape the point? 2 Diagrams
  3. Rung 3 Should they click or scan? 3 HTML page
  4. Rung 4 Does time order matter? 4 Explainer video

How to read it: section A is the ladder and a STE before/after. Section B is what Crank already does. Section C is proposed defaults for this experiments hub only. Section D is explicitly out of scope for now.

Crank practice marks locked choices. Proposed marks defaults that need Peter’s yes.

Section A · The ladder

Pick the cheapest rung that still works

Qualitative effort only: low, medium or high. No cost figures.

Agents can now produce large, custom, throwaway artifacts. Your attention is the bottleneck. Ask for the format that makes mistakes visible and decisions easy. If two rungs would work, pick the lower one unless you already know the reader is stuck.

Rung 1 · ~80% STE

When: bot reports, PR summaries, anything Peter reads to decide. Effort: low. Write short sentences. One instruction per sentence. Active voice. Use simple approved words. You do not need the full aerospace spec unless someone asked for it.

Rung 2 · Diagrams

When: flows, system maps, comparisons, “where does this sit?”. Effort: low to medium. Inline SVG on explainer pages keeps the repo self-contained and works at 375px width.

Rung 3 · HTML page

When: the reader should scan headings, follow links, or try a small interaction. Ask for output “in HTML” when you want a single file you can open or host. Effort: medium.

Rung 4 · Explainer video

When: the story only makes sense in order over time, like a proof or an animation pipeline. Effort: high. Narration can use a hosted voice or local TTS. Do not default here.

Before and after: the same paragraph at ~80% STE

The left box is how models often write. The right box is the same content steered toward simplified technical English.

Plain prose

When agents return long answers, you still have to judge whether the reasoning holds and whether you agree with the conclusions, which is slow because dense paragraphs hide how the argument is built and mix facts with opinions without signalling what matters most.

Before. One paragraph, many jobs.

~80% STE

Agents return long answers. You must judge the reasoning. You must judge the conclusions. Dense paragraphs hide the argument structure. Facts and opinions mix together. The text does not show what matters most. This work is slow.

After. Short sentences. One idea each.

Section B · What we already do

The “Better explained” skill already climbs the ladder

Crank practice One learning objective, one artifact, cheapest format that works.

The shared Better explained skill (see the uploaded skill in Crank tooling) states the format choice and reason before building. It prefers plain text at about 80% STE, then a chart when the point is numbers, then a self-contained web page for explainers and calculators, and treats explainer video as last resort when time order is the point.

Pages in this repo already follow that pattern:

  • Agent Engineering Map: diagrams first, progressive disclosure, long-form HTML explainer.
  • Video workflow and its FINDINGS section: HTML for the workflow, video only where motion is the subject.
  • Verification Gaps and Crank Architecture: same explainer shell, inline SVG, STE-leaning prose.
  • aivw-bpm comparison pages (internal, not in this repo): same “one page, one objective” habit.

The motion-film kit is Crank’s video rung: use it when the experiment is about picture change over time, not when a static diagram would do.

Proposed Section C · Defaults for Peter’s experiments hub

These defaults apply only to finished work in crank-experiments. They are not locked. Peter has not approved them yet.

  1. End every finished experiment with a one-page HTML summary. Title it “what happened and what we learned”. Link it from this hub’s experiment list instead of leaving the outcome in chat only.
  2. Write bot reports at ~80% STE. Short sentences, active voice, no metaphor where a mechanism should be named.
  3. Put a diagram first on any page that explains a flow. Match the existing explainers: hero SVG, caption, then prose.
  4. Throwaway pages are allowed. Label them throwaway in the title or meta so nobody mistakes them for permanent product docs.
  5. Video only when order in time is the point. Use the motion-film kit. Do not make video the default deliverable for experiments.
  6. Measure success by Peter’s speed to read and decide. If the format does not shorten that loop, climb one rung or fix the writing.

Section D · Not yet

Out of scope for this proposal

Named so nobody applies the ladder too early.

  • Client-facing output. Client reports and sends still need Peter’s review. This ladder is for internal experiments and explainers.
  • Production apps. Shipping Crank Engine tools keeps its own verification path. Do not replace Feature Maps and PR proof with a pretty page alone.
  • Video as the default. Even when tools make video cheap, default to STE plus diagrams plus HTML unless time order forces video.

Summary: as models do more legwork, human work shifts to oversight and understanding. You can ask for large, custom, throwaway artifacts that were not worth building by hand before. Pick the rung that makes that oversight fast.

Sources and credits

  • Andrej Karpathy, post on X, 2 October 2026: the ladder of formats (STE, diagrams, HTML, bespoke explainer video) and the shift toward oversight. Linked only; no metrics quoted.
  • Better explained skill: format choice order and ~80% STE writing rules used on this page.
  • Crank explainers in this repo: shared layout via scripts/build.mjs, shared styles in src/e/explainer.css.

How this page was made

Model: Composer (composer-2.5).

Token total: tokens: missing.

Built 9 October 2026 from Peter’s brief. Build note: src/e/understanding-ladder/BUILD-NOTE.md.