software-visual-explainerlisted

# Software Visual Explainer ## Core principle: stay in the loop The output exists for one reason: the human actually reads the artifact. Optimize every micro-decision (density, length, diagram choice, snippet selection) for "I will read this once" comprehension over "I have completely documented the topic." A 60% explanation the reader finishes beats a 100% one they won't open. Don't sacrifice clarity to save tokens — HTML is 2–4× more verbose than markdown and the cost is worth it. ## When to use Trigger phrases: "create an explainer", "help me understand X" (code/system topics), "make a visual walkthrough of this feature", "turn this spec into something readable", "single HTML file to explain this", "draw up what we've been discussing", "turn this brainstorm into an explainer". The input is either a **written artifact** (a spec, doc, or chunk of code) or **the conversation itself** (a brainstorm with no doc yet). The moment a brainstorm gets written to a spec, treat that spec as the written artifact and use ordinary document mode. Output: **one fully self-contained HTML file** by default, typically `docs/explainers/<topic>.html`. For exploration topics with genuinely separate deliverables, a linked web of HTML files is acceptable — each file its own complete artifact. ## When NOT to use - **Side-by-side option comparison grids** (e.g. "6 onboarding approaches") → sibling skill `code-option-comparison`. - **Design prototypes with live-tuning sliders**, or **throwaw