| name | interactive-explanation |
| description | Build a self-contained interactive or animated HTML page that explains how an algorithm or piece of code works. Use to pay down cognitive debt when a written explanation isn't enough. |
Interactive explanation
When a walkthrough still leaves an algorithm feeling like a black box, build an
animated, interactive explanation of it as a single HTML page.
Procedure
- Understand the algorithm first — read the source, or start from an existing
walkthrough.md if one exists.
- Build a single self-contained HTML page under
notes/explanations/ that
animates the algorithm step by step. Design for insight: show the
intermediate states and decisions (attempted placements, comparisons,
backtracking) that make the mechanism click, not just the final result.
- Include playback controls: pause, speed adjustment, and frame-by-frame
stepping while paused. Let the user supply their own input where it makes
sense (persisting it in the URL
#fragment so links are shareable).
Style rules (HTML tools)
- Never use React — plain HTML, vanilla JavaScript and CSS, minimal
dependencies. The page must work by opening the file, with no build step.
- CSS: two-space indents, start with
* { box-sizing: border-box; }.
- Inputs and textareas: font size 16px. Prefer Helvetica.
- JavaScript:
<script type="module">, two-space indents.
- Prefer Sentence case for headings.