explain-better

Goal: help the user understand something fast. Oversight and understanding is the bottleneck now, not output. Output is cheap, so make a custom, throwaway artifact. Input: `$ARGUMENTS` ## Pick the format If the first word of the input is `writing`, `diagram`, `html`, or `video`, use that format. Otherwise pick the lowest rung that fits. Each rung is richer than the one before. | Rung | Format | Use when | | --- | --- | --- | | 1 | ASD-STE100 writing | The idea is a sequence, a rule, or a definition. | | 2 | Diagram | The idea has parts and links, a flow, or a hierarchy. | | 3 | HTML page | The idea needs interaction, many diagrams, or animation. | | 4 | Explainer video | The idea is a process that changes over time, and the user wants to watch it. | Do not ask which format. State the pick in one line, then do it. If the user is unsure, offer the next rung up at the end. ## 1. Writing: ASD-STE100 ASD-STE100 is Simplified Technical English. It was made for aerospace maintenance manuals. - Maximum 20 words per instruction sentence. Maximum 25 for descriptive text. - One instruction per sentence. - Active voice. Simple tenses. No `-ing` verb forms except technical nouns. - One word for one meaning. Never rotate synonyms. - Plain, short words. Define each technical term at first use. - Paragraphs: one topic, maximum 6 sentences. Use lists for 3 or more steps. The full spec is strict. If the result reads stiff, relax to "80% of the way to ASD-STE100": keep the short sentences and the one-word-one-meaning rule, and allow some passive voice and tenses. ## 2. Diagram Load the `artifact-diagramming` skill first. Draw the real mechanism: the parts, the links, and the direction of data or control. Label every arrow with what travels on it. Use inline SVG or Mermaid. Add at most 3 sentences of text. ## 3. HTML page Load the `artifact-design` skill, then build one self-contained `.html` file. Put these in it: - A short summary at the top. - Diagrams, with hover or click to show detail. - Small interactive parts where they help (sliders, step buttons, toggles). - No external build step. Check the page with a headless browser tool such as Playwright. Open it in the browser with a local file URL. ## 4. Explainer video (3Blue1Brown style) 1. Write a short script first: 5 to 10 scenes, one idea per scene. Show the script to the user only if the topic is large. 2. Build the scenes with Manim (`pip install manim`) or Remotion. Use Manim for math and diagrams. Use Remotion for UI and text. 3. Narration, in this order: 1. ElevenLabs, if the user has a key. Read it from an environment variable or a secrets manager. Never print the key or write it to a file. If no key is found, go to step 2. 2. A free local option: macOS `say`, or Piper or Kokoro TTS. 4. Render to `.mp4`, then open it for the user. Name the output path in the reply. Render a low-quality preview first (`manim -ql`). Render the final file only after the preview works. ## Rules - Do not ship a diagram, page, or video for a trivial question. Use rung 1. - Keep the artifact discardable. Write it in the scratchpad or a `explain/` folder, not in a project repo, unless the user names a path. - End with one line: what was made, where it is, and what the next rung up would add.