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

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.