Visual Explain

Explain concepts visually using ASCII diagrams, tables, flow charts, and structural maps. The visual IS the explanation — prose is secondary.

When to invoke

Trigger phrases: "explain visually", "show me a diagram", "draw this out", "chart this", "map this", "visualize this", "show me how this works", "diagram this", "sketch this out".

Also invoke when /visual-explain is used directly.

Visual vocabulary

Use the right format for the right job:

Rules

1. Lead with the visual. Always produce the diagram or table FIRST. Prose comes after, if needed at all.
2. Minimal prose. Keep explanatory text to 1-2 sentences per diagram. The visual carries the explanation — prose only clarifies what the visual cannot.
3. Prefer multiple small diagrams over one complex one. Break a system into 2-3 focused visuals rather than cramming everything into a single diagram. Each diagram should have one clear point.
4. Consistent visual language:
   • [ boxes ] for components, modules, services
   • ──▶ or → for data flow and control flow
   • ─── for connections and relationships
   • < diamonds > for decisions
   • ( rounded ) for inputs/outputs
   • │ and ─ for structure lines
5. System explanations follow this order:
   • Structure first (what are the parts, how do they relate)
   • Data flow second (what moves between them)
   • State changes third (how things evolve over time)
6. Comparisons follow this order:
   • Table first (options as columns, criteria as rows)
   • Annotate the recommended choice with a brief reason below the table
7. Keep diagrams under 40 lines tall and 72 characters wide. If a diagram exceeds this, split it into multiple diagrams with clear labels.

Examples

Flow diagram

  [ User Request ]
         │
         ▼
  [ Auth Middleware ] ──▶ [ 401 Unauthorized ]
         │
         ▼
  [ Route Handler ]
         │
    ┌────┴────┐
    ▼         ▼
 [ Cache ] [ Database ]
    │         │
    └────┬────┘
         ▼
  [ Response ]

Comparison table

                 Option A        Option B        Option C
  ──────────────────────────────────────────────────────────
  Speed          Fast            Medium          Slow
  Cost           $$$             $$              $
  Complexity     High            Medium          Low
  Reliability    High            High            Medium
  ──────────────────────────────────────────────────────────
  ✓ Recommended: Option B — best balance of cost and speed.

Sequence diagram

  Client          Server          Database
    │                │                │
    │── POST /api ──▶│                │
    │                │── INSERT ─────▶│
    │                │◀── OK ─────────│
    │◀── 201 ────────│                │
    │                │                │

Hierarchy / tree

  egregore/
  ├── bin/            Shell scripts (Runtime, notifications, telemetry)
  ├── skills/         Cognitive skill definitions
  │   ├── harvest/
  │   └── tui-design/
  ├── memory/         Symlink → shared memory repo
  │   ├── people/
  │   ├── handoffs/
  │   └── knowledge/
  └── .claude/
      ├── commands/   Slash command definitions
      └── skills/     Claude Code skill files

Before/after

  BEFORE                          AFTER
  ┌──────────────────┐            ┌──────────────────┐
  │ Monolith         │            │ API Gateway       │
  │  ┌────────────┐  │            │                   │
  │  │ Auth       │  │            └─────────┬─────────┘
  │  │ API        │  │                      │
  │  │ DB         │  │              ┌───────┼───────┐
  │  │ Queue      │  │              ▼       ▼       ▼
  │  └────────────┘  │           [ Auth ] [ API ] [ Worker ]
  └──────────────────┘              │       │       │
                                    └───┬───┘       │
                                        ▼           ▼
                                     [ DB ]     [ Queue ]