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

1. Detect styles: Which styles fit this topic? Most need a trace + summary table.
2. Concrete example first: Pick the smallest useful example. Never start abstract.
3. Initial state: Draw the starting diagram with all elements labeled.
4. Step through: Show each intermediate state. One diagram per step. Annotate what changed and why.
5. Summarize: End with a table, formula, or key insight.
6. 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 BELOW

Step-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 ^^^^^ or written/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   ║▒▒▒▒▒▒│▒▒▒▒▒▒│
└──────┴──────╨──────┴──────┘
               ^^^^^^^^ free

Multi-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 = 10

Concept 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:

• --ascii for 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.