output-ladder

# Understanding-First Output Ladder Turn a learning goal into a suitable output format and a ready-to-use prompt. Generate prompts by default; create the actual artifact only when the user requests it. ## Source and scope Inspired by [Andrej Karpathy's original post](https://x.com/karpathy/status/2105819303471976479) about understanding language-model outputs through writing, diagrams/images, interactive web pages, and bespoke explainer videos. Karpathy presents these media progressively, mentions ASD-STE100 and 3b1b-style explainers, and advocates custom, discardable software artifacts. The name “Understanding-First Output Ladder,” L1–L4 labels, selection rules, and templates below are this project's extensions, not a named methodology from the original post. Use this framework for personal learning, concept demonstrations, and explanation prototypes. For authoritative documentation or maintained teaching material, use the required format and sourcing process; this framework can supplement them. ## Inputs Accept natural-language requests; these fields are convenient shorthand, not a required parser: - `topic`: Concept, system, or algorithm to understand. Required; ask if absent and not inferable. - `audience`: Beginner, intermediate, or expert. Default to intermediate when no context indicates otherwise. - `preference`: L1–L4, writing, diagram/image, web, or video. Honor an explicit choice. - `constraints`: Such as offline, no API keys, frontend only, duration, budget, or accessibility requirements. Use the user's language for explanations and prompts unless requested otherwise. Resolve a material conflict between preference and constraints before producing an incompatible prompt. Otherwise proceed with reasonable assumptions and include those that affect correctness in the prompt. ## Select the medium Identify the learning outcome: what should the learner be able to explain, predict, compare, or do? Consider structure, change over time, interaction, narrative, and audience knowledge. | Level | Medium | Choose when | | --- | --- | --- | | L1 | Clear writing | Definitions, distinctions, rules, or reasoning benefit mainly from precise language. | | L2 | Diagrams / images | Spatial structure, relationships, flows, or comparisons are the main bottleneck. | | L3 | Interactive web | The learner benefits from changing inputs, stepping through a process, or comparing outcomes. | | L4 | Explainer video | A guided sequence, coordinated animation, or narrative helps explain change or build an argument. Interaction is not required. | Choose the simplest medium that meets the learning outcome and constraints. Higher levels offer richer media, not guaranteed deeper understanding. A dynamic topic may suit either L3 or L4: use L3 for learner-controlled exploration and L4 for guided exposition. Recommend a combination only when the parts serve distinct learning needs. If the user specifies a medium, use it and explain how to make it effective instead of reopening format selection. ## Build the prompt Produce a self-contained, copyable prompt with: 1. Topic, audience, prerequisites, and a concrete learning outcome. 2. Output medium and deliverable, including technical constraints where relevant. 3. The core content and the particular structure, interaction, or narrative that supports understanding. 4. Assumptions, simplifications, and checks needed for subject accuracy. 5. Observable success criteria: for example, predict the next state or explain why two outcomes differ. Apply the user's constraints to the main prompt, alternative prompts, and practical tips alike. ### Medium-specific guidance - **L1:** Use plain, precise language and define unfamiliar terms. ASD-STE100-inspired writing is an option, especially for technical English. Do not claim formal compliance without checking the applicable vocabulary and rules; a sentence-length limit alone is insufficient. For other languages, use their own clear-writing conventions. - **L2:** Specify the diagram type, labels, relationships, and legend. Prefer Mermaid for supported logical diagrams; use another format when spatial or pictorial content requires it. Include a text explanation of the essential relationships. - **L3:** Specify meaningful controls, visible feedback, initial conditions, reset behavior, and informative edge cases. For lightweight prototypes, prefer a self-contained HTML/CSS/JS page unless the user's stack requires otherwise. Include labels and keyboard-operable controls; avoid relying on color alone. - **L4:** Specify duration, audience, narrative sequence, storyboard, animation, captions, and narration requirements. For executable output, request source plus rendering instructions and name the toolchain. Treat a script or storyboard as a separate deliverable from a rendered video. If no rendering tool is available, state what can be delivered. Describe desired visual qualities; “3b1b-inspired” can be a reference, but do not imply affiliation or copy branded assets. ### Accuracy and feasibility Disposable artifacts reduce maintenance needs, not factual standards. Require checks of key facts, equations, transitions, and simulated behavior. Name algorithm variants when behavior differs between them, label approximations, and distinguish illustrative models from real-world implementations. Request sources when claims need verification; never invent citations. For `offline`, exclude runtime network calls, CDNs, remote fonts, and cloud speech services. State any one-time installation or download requirements separately; if setup must also be offline, use only locally available dependencies. gTTS uses an online service and is not an offline narration option. Use an available local TTS engine, supplied audio, or captions without narration as appropriate. For `no API keys`, select tools that do not require credentials; this does not imply offline operation. Suggest tools only when relevant and do not guarantee current pricing or availability. Mermaid, D2, or Graphviz can serve diagrams; native web code can serve interactions; Manim or Remotion can serve video source. These are optional choices, not required dependencies of this skill. ## Response contract Keep the explanation brief and put most detail into the main prompt: **Topic analysis:** Two or three sentences identifying the learning bottleneck and relevant audience assumptions. **Recommended level:** L1–L4, medium, and a one-sentence rationale. Use **Selected level** when honoring the user's preference. **Ready-to-use prompt:** One fenced text block containing the complete prompt. **Alternative options:** Up to two useful alternatives with short, copyable prompts. Use only L1–L4, never L0 or L5. Describe the distinct benefit rather than assuming neighboring levels are lighter or deeper. Omit alternatives when the user requests only one format. **Practical tips:** One to three topic-specific suggestions for verification or iteration, respecting all constraints. ## Example Input: “Help me understand TCP congestion control, beginner audience, interactive web, offline, no external dependencies.” **Topic analysis:** The main bottleneck is connecting packet-loss signals to changes in the congestion window. A simplified TCP Reno model can show these changes while keeping the assumptions visible. **Selected level:** L3 — Interactive web. Adjustable loss events let the learner compare timeout and duplicate-ACK responses. **Ready-to-use prompt:** ```text Create a self-contained HTML/CSS/JS page teaching simplified TCP Reno congestion control to beginners. It must work offline with no external dependencies or network requests. Learning outcome: The learner can predict how cwnd and ssthresh change after a timeout or three duplicate ACKs and explain how slow start differs from congestion avoidance. Show a cwnd-over-time chart with labeled units and the current phase. Provide step, play/pause, reset, initial-ssthresh controls, and separate buttons for timeout and three duplicate ACKs. Include fast recovery and annotate important transitions. Make controls keyboard-operable and explain events in text as well as color. State the model's update rules and assumptions, including discrete RTT steps, the chosen Reno fast-recovery behavior, and omissions such as receiver-window limits. Distinguish this teaching model from a production TCP implementation. Check phase transitions and loss responses against the stated Reno rules. Include two worked traces, one per loss event, and a short prediction exercise with an explanation of the answer. Deliver the complete HTML file and instructions to open it locally. ``` **Alternative option:** L2 — “Create a Mermaid state diagram of the same simplified TCP Reno model, including slow start, congestion avoidance, and fast recovery. Label transitions with triggers and cwnd/ssthresh updates, and list model assumptions.” **Practical tip:** Verify both worked traces before adding visual polish; the diagram and simulator should use the same update rules.