visualize

A diagram loads two cognitive channels; prose loads one. Verbal and visual information travel separate paths (dual-coding theory), and working memory saturates fast (cognitive load theory). A labeled diagram lets a reader grasp structure at a glance and hold it longer. This skill converts a thing-with-structure into the visual that carries it best.

Scope: structure, flow, state, sequence, hierarchy, comparison, quantity. If the answer has no structure — a single fact, a yes/no — do NOT force a diagram. Say it.

1. Identify what has structure. Read the source if needed (Read/Grep/Glob a file, function, or directory). Find the entities and the relationships between them — that is what the diagram encodes.
2. Match intent to format (table below). One intent → one primary format. Do not mix three diagram types in one figure.
3. Choose the render target. Terminal/chat → ASCII. GitHub/PR/markdown viewer → mermaid is allowed. When unsure → ASCII (it renders everywhere).
4. Draw it, then prune. Apply the quality bar. Cut every element that carries no meaning.
5. Add only the prose the picture cannot encode — the why, a caveat, the next step.

• MUST default to ASCII / Unicode box-drawing + Markdown tables. They render in the Claude Code terminal TUI, IDE panels, and GitHub.
• MUST use a ```mermaid block ONLY when output targets GitHub, a PR, or a markdown viewer. The terminal TUI does NOT render mermaid — it prints the raw source. Never make mermaid the sole representation in a terminal reply. When both terminal and GitHub are in play, lead with ASCII; offer mermaid as an addition if asked.
• SHOULD keep box-drawing characters consistent within one figure: ┌ ┐ └ ┘ ├ ┤ ┬ ┴ ┼ │ ─ for boxes, → ← ↑ ↓ for flow.

Badly built diagrams read as visual noise — worse than prose. Enforce:

• Coherence — exclude every element that does not carry meaning. Fewer nodes wins.
• Spatial contiguity — labels inside or directly beside what they label, never in a separate paragraph.
• Size — under ~15 nodes per figure. Bigger → split into layers or show the top level and drill down on request.
• No redundancy — do not restate in prose what the figure already shows.

For copy-ready ASCII shapes — architecture, tree, flowchart, state machine, sequence, quantity bars — read references/diagram-templates.md.