workbuddy_skills/session-mechanism/references/karpathy-output-ladder/SKILL.md

---
name: karpathy-output-ladder
description: "Produce layered explanations that climb Karpathy's LLM output ladder. Rung 1 is tight ASD-STE100 controlled plain text. Rung 2 is a diagram that marks the least-certain part. Rung 3 is a single self-contained interactive HTML page. Use when the user asks to explain, teach, show, or make a visual of a topic and wants the answer to escalate from words to diagram to interactive page, or references Karpathy output ladder or writing hierarchy. Combines controlled prose, diagramming, and standalone HTML delivery in one workflow."
agent_created: true
---

# Karpathy Output Ladder (Rungs 1–3)

## Overview

Turn any "explain / teach / show me" request into a three-step escalation, in order of
expressiveness and effort:

- **Rung 1 — Controlled text.** A short, unambiguous explanation written to the ASD-STE100
  controlled-English rules (see `references/ste100.md`).
- **Rung 2 — Diagram.** One SVG or Mermaid diagram that shows the structure, **with the
  single most uncertain or assumption-heavy part visibly flagged**.
- **Rung 3 — Interactive page.** One self-contained HTML file (inline CSS + JS, no external
  dependencies) that lets the reader explore the topic through tabs, accordions, or toggles.

Each rung builds on the previous one. A diagram that contradicts the text, or an HTML page
that drops the flagged uncertainty, is a failed deliverable. Always deliver rungs in
sequence and carry the "least-certain" marker up the ladder.

## When to Use

Trigger this skill when the user:

- Asks to explain, teach, clarify, or "show" a concept, mechanism, or process.
- Says "make a diagram / chart / visual" alongside an explanation.
- Wants a standalone HTML explainer, interactive page, or long-scroll infographic.
- References Karpathy's output ladder, the "writing hierarchy", or "rungs" of LLM output.
- Wants a topic rendered at increasing fidelity (words → picture → interactive).

If the user wants only one rung (e.g. "just a diagram"), still apply the relevant rung's
rules below, but skip the others.

## Workflow

### Rung 1 — Controlled text (always first)

Write the explanation before drawing anything. Follow `references/ste100.md`:

- Procedural (instruction) sentences: ≤ 20 words. Descriptive sentences: ≤ 25 words.
- Each paragraph: ≤ 6 sentences.
- Prefer active voice. Use one word for one meaning. Keep noun clusters ≤ 3 words.
- Use approved verbs (check, start, stop, use, show, open, close, set, get, make, …).
- No metaphors, no hype words, no double negatives.

Output a compact block of 3–8 sentences that a non-expert can parse. This block becomes the
caption / intro for Rung 2 and the summary panel for Rung 3.

### Rung 2 — Diagram with a "least-certain" flag

Pick the single diagram that carries the idea:

- **Flow / process / decision** → Mermaid `flowchart` or `sequenceDiagram`.
- **State machine / lifecycle** → Mermaid `stateDiagram-v2`.
- **Spatial / custom / branded** → hand-written inline SVG (viewBox `0 0 680 …`).

Rules:

- One concept per diagram. Label every node in plain words.
- **Mark the least-certain part**: dashed border + a `⚠ least certain` tag, or a muted
  color, so the reader sees where the explanation is weakest. This is mandatory, not
  optional — it is the core discipline of the ladder.
- Keep it minimal; do not decorate.

If the diagram would need more than ~12 nodes to be honest, split it or fall back to text.

### Rung 3 — Self-contained interactive HTML

Copy `assets/html-template/index.html` as the starting point. Then:

- Keep everything inline: `<style>` in `<head>`, `<script>` at end of `<body>`. No CDN,
  no `<link href>`, no build step. The file must open from `file://` with zero network.
- Structure the page: a one-line title, the Rung-1 summary, the Rung-2 diagram (embed the
  SVG/Mermaid), then interactive sections (tabs or accordion) that expand each part.
- Add at least one real interaction: tab switch, accordion open/close, hover reveal, or a
  scroll-triggered fade. Prefer subtle motion over spectacle.
- Keep the "least-certain" flag visible in the page (a callout box that links to the
  diagram's dashed node).
- Include `<meta name="viewport" content="width=device-width, initial-scale=1">` and a
  dark/light-safe color scheme.
- Target a single file under ~80 KB. If larger, move sample data out or trim.

Deliver the HTML file via `present_files` so the user gets a live preview.

## Acceptance Checklist

- [ ] Rung 1 text obeys the STE100 length and voice rules.
- [ ] Rung 2 diagram exists and flags exactly one least-certain part.
- [ ] Rung 3 HTML is one self-contained file, opens offline, and surfaces the flag.
- [ ] The three rungs agree with each other (no contradictions).

## Resources

- `references/ste100.md` — Verified ASD-STE100 rules, approved-verb list, official PDF link,
  before/after examples. Load this whenever writing Rung 1 text.
- `references/ladder-workflow.md` — Deeper notes on diagram choice and HTML conventions.
- `assets/html-template/index.html` — Copy-ready self-contained interactive page scaffold.