Legible explainer skill

Legible explainer

As agents do more of the work, the human job moves toward oversight and understanding. The format of an explanation decides how fast a reader understands it. Karpathy's ladder, from cheapest to richest:

1. STE prose: ASD-STE100 rules (short sentences, one meaning for each word, active voice, approved verb forms) make text much easier to read. Default to about 80% of the way to strict STE, because full STE is stiff.
2. Diagram: structure, sequence and state are faster to see than to read.
3. HTML page: a dense, self-contained page with several views of the same subject. Here it is a "spec sheet" in the visual language of an engineering drawing: zone frame, lettered panels, title block.
4. Explainer video: narration plus motion, for subjects that unfold in time.

Each tier reuses the one below it. Sheet text is STE. Video scenes come from sheet panels. A good result at a lower tier is a better answer than a weak result at a higher tier.

Pick the tier

An explicit request for a format always wins ("in HTML", "draw", "video", "in STE"). Otherwise choose the lowest tier that fully serves the reader:

Signal in the request	Tier	Output
A direct question, a procedure, a short concept, or "explain in STE"	1 STE prose	The answer in chat, sized to the question
The subject is a sequence, flow, hierarchy, state machine or architecture; "draw", "diagram", "something to keep open"	2 Diagram	One .html page with an inline SVG diagram
Several facets (parts, rules, numbers, history, risks); "overview", "one-pager", "explainer page", an explanation "in HTML"; or "help me understand this long output / plan / diff / spec"	3 Spec sheet	One self-contained .html sheet, sized to the subject
"Video", "3b1b style", "narrated", "animated explainer"	4 Video	An .mp4 with narration: Manim for a 3Blue1Brown look, otherwise the hyperframes skill

Neighbouring skills, when they are installed: a production page, app UI or dashboard belongs to frontend-design; a diagram the user will keep editing belongs to excalidraw-diagrams; a promo or product video belongs to hyperframes on its own. Use this skill when the reader's understanding of a subject is the product.

Offer the next tier in one line only when the subject shows that tier's signal and the user named no format (a request for STE is a writing style, not a format): a diagram when the answer has a sequence, flow or state; a sheet when it has several facets; a video only when the subject unfolds in time. Do not offer after a short tier 1 answer, after a video, or a video for a document review.

Answer first (every tier)

The reader asked a question. Whatever the tier, the first thing they read is the answer: the difference, the verdict, the cause, in one or two sentences. Then the support. Answer the topics the user named, at the depth they asked for; give a side topic one line, or leave it out. A longer answer is not a better answer.

Write in STE (every tier)

Read references/ste-writing.md before you write the first sentence. The core:

• At most 20 words in an instruction, 25 in a descriptive sentence, 6 sentences in a paragraph, one topic in a paragraph. A number and its unit count as one word.
• One instruction in each sentence. Put a condition first. Start a WARNING or CAUTION with the command, then give the risk.
• Verb forms: imperative, simple present, simple past, simple future, infinitive, and the past participle as an adjective. No -ing verb forms (progressive, gerund, participle) except inside a technical noun. No perfect tenses. No phrasal verbs ("set up", "carry out").
• Active voice. No passive in instructions. In descriptions, the passive only when the agent is not known.
• One word for one meaning, the same word for the same thing every time. Technical nouns and technical verbs of the subject are allowed, each only in its own part of speech. Multi-word nouns of 3 words at most. No semicolons. American spelling.

The dial. "80%" (default) keeps all the grammar above and relaxes the word list: keep a non-STE word when the STE word is clumsy or changes the meaning. "Strict" (when the user asks for it) also replaces every unapproved word you know of; when a sentence cannot be both strict and clear, rewrite it, and if that fails, tell the user which sentence breaks which rule.

Keep the meaning. When you simplify a source, keep its certainty ("should" stays an expectation), conditions, negations, attributions, numbers and units. A simpler sentence that says more or less than the source is wrong.

House style (opinionated defaults on top of STE; edit them to taste): no em dashes; never the word "caveat"; never open with a headcount ("three things to check"), introduce a list by its subject ("What to check:"); no "X, not Y" framing, state what is true as its own sentence; no emoji; add an as-of date to a number that can change.

Lint what you write, with the mode you are writing in:

python3 <skill-dir>/scripts/ste_lint.py <file> --mode 80          # or --mode strict
printf '%s' "$DRAFT" | python3 <skill-dir>/scripts/ste_lint.py - --mode 80   # a chat answer (stdin is read as Markdown)

The linter fails on grammar errors (length, verb forms, voice, semicolons, dashes, house style) and warns on word-level findings. It knows a short list of common unapproved words; the STE dictionary is the authority. PASS means the floor is met: fix every finding that is not a false alarm, and keep an unapproved word only on purpose. Quote non-STE text on purpose (an "original text" in a before-and-after, a line from a source document) inside data-ste="ignore" in HTML, or between <!-- ste-ignore-start --> and <!-- ste-ignore-end --> in Markdown. Pass technical nouns of the subject with --allow word1,word2.

Be right before you are clear

A clear explanation of a wrong fact is worse than no explanation.

• Verify facts that can drift (versions, dates, limits, prices) before you write them, and add an as-of date.
• Do not copy a fact from an example or reference image without checking it. Examples can be wrong.
• When you explain a document the user gave you (a plan, a diff, an agent's output), every claim must trace to that source: name the section or line. When the source does not say something, write "Not stated in the source". Then check the document against itself (references/spec-sheet.md, "Sheets that explain a document"): the gaps it does not name are what the reader most needs. Keep your own assessment visibly separate from what the source says.
• Do not pad. Each panel, sentence and diagram node must answer a question the reader has.

Tier workflows

• Tier 1: write the answer in STE, in chat. Open with the answer to the question, then the detail for each topic the user named. A question with a few named topics usually needs 500 to 1,000 words; count them before you send. Use a vertical list for steps or parallel items; headings name the subject. Lint the draft through stdin. Write a .md file as well only when the user asks for one or the answer is a reference they will keep; the chat still carries the full answer.
• Tier 2: read references/diagram.md. Hand-draw the SVG (no diagram libraries, no CDN scripts) in the sheet's visual language, with STE labels and numbered steps.
• Tier 3: read references/spec-sheet.md, then copy assets/spec-sheet-template.html and replace all its demo content, including the <title>. Plan the panels first: one panel for each question the reader has.
• Tier 4: read references/video.md. Choose the engine (Manim for a 3Blue1Brown look, hyperframes for other styles) and the voice, plan a title card with a one-line intro, the body and a recap card, write the narration and a scene plan, build at a calm pace with burned-in captions and a quiet music bed, and check the render.

Deliver

• Write the file into the user's current project: docs/reports/ when it exists, otherwise the project root, with a short descriptive filename. Do not publish it as an Artifact or upload it anywhere.

• Pages are self-contained: CSS, JavaScript and images inline (images as data URIs). The only network request allowed is Google Fonts, with a real fallback font stack. The file must open from file://.

• Check every page before you hand it over. Keep the check output out of the project:

  python3 <skill-dir>/scripts/check_page.py <page.html> --out <scratch-dir>/<page>-check
  python3 <skill-dir>/scripts/ste_lint.py <page.html> --mode 80   # or strict
  

  check_page.py renders at 1440, 1280, 1024, 800 and 390 px and prints to A4. It fails on network requests, overflow, clipped content, annotation labels that collide or sit on text, SVG labels that collide or leave the SVG, text-wrap: balance|pretty, max-width on text, one-sided accent marks, dashes, emoji, JavaScript errors, and a sheet that needs more than one A4 page. Fix every error, then read the screenshot tiles it lists at full size. A pass does not prove the page is good: look for text that wraps while space remains, dead space, and labels that point at the wrong thing.

• When the user will print or pin the page, ship the PDFs that check_page.py writes: copy print.pdf to <slug>.pdf, and for a spec sheet also print-a3.pdf to <slug>-A3.pdf (the A3 sheet has readable type on a wall; the A4 one fits a desk printer with small type). Say which is which.

The chat reply is the answer. The user reads the chat first and may never open the file. For every tier:

1. The answer in one or two sentences (the verdict, the difference, the key fact). For a document review, include what the document proposes, the conditions written as checks the user can make ("Confirm that ..."), the questions to ask the author, and a sentence the user can say at their meeting.
2. The few points that support it, in STE.
3. The file path(s), and one line on what the file adds (the diagram, the full risk table).
4. Only then, and only if they change what the user does: assumptions you made, one at most, and the next-tier offer when the offer rule allows it.

Leave out how you worked: linter results, test widths, tool installs, git state. One short line ("Checked at five widths and in print.") is enough. When the user asked for an STE level in a longer answer, end with one line on what you kept and what you relaxed ("80% STE: the grammar rules kept, a few non-STE words kept for clarity."). Leave it out of a short answer. When a shape is the point (a curve over time, a sawtooth), put a small inline text sketch in the tier 1 answer instead of only offering a diagram. For a reference sheet, the reply gives the few rules or facts the reader will use most, then the paths. Do not paste a whole page into chat, but never make the user open a file to get the answer.

• The STE label is for the user who asked for STE. Write in STE always; put "80% ASD-STE100" in a title block or a reply only when the user asked for STE.

Files in this skill

• references/ste-writing.md: STE rules by section, the dial, substitution table, before-and-after examples.
• references/diagram.md: tier 2 diagram rules and SVG patterns.
• references/spec-sheet.md: tier 3 layout, panel catalogue, document sheets, design rules.
• references/video.md: tier 4 structure (title, body, recap), voice and pace, music, captions, scene plan and hyperframes hand-off.
• assets/spec-sheet-template.html: a working sheet with every component (demo topic: HTTP caching).
• scripts/ste_lint.py, scripts/check_page.py: checkers. Both have --self-test.