| name | visual-explain |
| description | Explain concepts visually using ASCII diagrams, flow charts, tables, and structural maps. Use when asked to explain, compare, or show how something works. |
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:
| Concept type | Visual format |
|---|
| Flows and pipelines | ASCII arrow diagrams (→, ↓, ──▶) |
| Architecture / components | Box diagrams with labeled connections |
| Comparisons and trade-offs | Tables with columns per option |
| Hierarchies and containment | Tree structures or nested box diagrams |
| Temporal sequences | ASCII sequence diagrams (actor columns + arrows) |
| State changes | Before/after side-by-side diagrams |
| Decision logic | Flowcharts with diamond decision nodes |
Rules
-
Lead with the visual. Always produce the diagram or table FIRST. Prose comes after, if needed at all.
-
Minimal prose. Keep explanatory text to 1-2 sentences per diagram. The visual carries the explanation — prose only clarifies what the visual cannot.
-
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.
-
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
-
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)
-
Comparisons follow this order:
- Table first (options as columns, criteria as rows)
- Annotate the recommended choice with a brief reason below the table
-
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 (graph, notify, 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 ]
