Visual Trace Explanations
Explain concepts using hand-drawn ASCII diagrams with step-by-step state progression. Every intermediate state is shown — never skip steps.
Style Selection
Pick the style(s) that fit the topic. Combine freely — most explanations use 2-3 styles together.
| Style | When to Use |
|---|---|
| Visual Trace | Step-by-step state changes through a process (algorithm walk, mechanical cycle, signal flow) |
| Block Diagram | Showing structure or layout (memory, circuits, architecture, anatomy) |
| Comparison Table | Contrasting 2+ things (alternatives, tradeoffs, before/after) |
| Formula Derivation | Building up to a formula or rule from first principles |
| Concept Breakdown | Explaining what something is to someone with zero background |
Workflow
- Detect styles: Which styles fit this topic? Most need a trace + summary table.
- Concrete example first: Pick the smallest useful example. Never start abstract.
- Initial state: Draw the starting diagram with all elements labeled.
- Step through: Show each intermediate state. One diagram per step. Annotate what changed and why.
- Summarize: End with a table, formula, or key insight.
- Connect: Link back to the bigger picture or real-world application.
Formatting Rules
Box-Drawing Characters
Use Unicode box-drawing for all diagrams:
Cells: ┌──────┬──────┬──────┐
│ A │ B │ C │
└──────┴──────┴──────┘
Pointers: ↓ ↑ ← → (single direction)
↕ ↔ (bidirectional)
Labels: Place pointer name ABOVE the arrow, value annotation BELOWStep-by-Step Traces
Each step gets its own diagram. Show:
- Pointer positions with labeled arrows
- What decision was made and why (annotation to the right)
- What changed highlighted with
^^^^^orwritten/moved/swapped
Step N: description of what happens
ptr1 ptr2
↓ ↓
┌──────┬──────┬──────┬──────┐
│ 10 │ 20 │ 30 │ 40 │ 10+40=50 > target → ptr2--
└──────┴──────┴──────┴──────┘Before/After Pattern
For transformations, show both states:
Before:
┌──────┬──────┬──────┬──────┐
│ A │ dead │ B │ dead │
└──────┴──────┴──────┴──────┘
After:
┌──────┬──────╫──────┬──────┐
│ A │ B ║▒▒▒▒▒▒│▒▒▒▒▒▒│
└──────┴──────╨──────┴──────┘
^^^^^^^^ freeMulti-Phase Explanations
Separate major phases with heavy dividers:
═══════════════════════════════════
PHASE 1: Description
═══════════════════════════════════Comparison Tables
Use markdown tables with concrete values, not vague descriptions:
| Input size | Approach A | Approach B | Speedup |
|---:|---:|---:|---:|
| 100 | 4,950 | 99 | 50× |
| 1,000 | 499,500 | 999 | 500× |Formula Derivation
Build up visually. Show the trick, not just the result:
Write sum forwards and backwards, add vertically:
4 3 2 1
+ 1 2 3 4
───────────────
5 5 5 5 → 4 × 5 = 20 → 20/2 = 10Concept Breakdown
When explaining to a non-expert:
- No jargon without immediate definition
- Use analogies tied to physical intuition
- Build from what they know to what they don't
- Use "think of it like..." bridges
Diagram Tool Selection
- Hand-drawn ASCII (default): Step-by-step state progressions, array walks, pointer movements — anything where intermediate states matter.
- doc-mermaid-ascii (invoke as companion): Algorithm flowcharts, decision trees, state machines, sequence diagrams, entity relationships — structural overviews.
- Both together: Use doc-mermaid-ascii for the overview flowchart, then hand-drawn traces for the step-by-step walkthrough.
When invoking doc-mermaid-ascii:
--asciifor inline terminal output-o file.svg --theme <name>for themed SVG files
Constraints
DO:
- Show every intermediate state — never skip steps
- Use the smallest example that demonstrates the concept (5-8 elements, not 20)
- Annotate decisions to the right of each diagram (
10+40=50 > target → R--) - End with a summary table or key insight
- Adapt to ANY domain — not just CS
DON'T:
- Start with theory — start with a concrete example
- Use jargon without defining it first
- Show only the final result — the journey IS the explanation
- Make diagrams wider than ~80 characters (terminal readability)
- Use Mermaid for step-by-step traces — hand-drawn ASCII is clearer for state progression
Load references/style-guide.md for the full character reference and reusable patterns. Load references/examples.md for curated examples of each style.