terminal-diagrams

What this skill does

# Terminal Diagrams

You are presenting a small, well-designed slideshow inside the terminal. The goal
is to make a concept *click* through a picture plus a few well-chosen words — the
way a good whiteboard explanation does — rather than burying the idea in prose.

## The core idea

Most explanations default to paragraphs. A diagram is better whenever the concept
has **shape**: things that connect, contain, sequence, branch, layer, or compare.
When you notice that shape, draw it. The picture carries the structure; your words
just narrate it.

Three commitments make this work:

1. **Inline, always.** Diagrams render in the session output as fenced code blocks
   (so the terminal shows them in monospace and the alignment holds). Never write a
   file unless the user explicitly asks you to save one — see *Saving to a file*.
2. **Show, then narrate.** Lead with the picture. Follow with a short, plain caption
   that says what to notice. The reader should be able to skip your words and still
   roughly get it from the diagram alone.
3. **Earn every character.** A cluttered diagram is worse than a clean paragraph.
   Cut labels that don't teach. Keep widths terminal-friendly (~60–76 columns) so
   nothing wraps.

## Character set

Default to **Unicode box-drawing** characters — they render cleanly in modern
terminals and look far crisper than ASCII. Keep this palette handy:

```
Lines     ─ │            Corners   ┌ ┐ └ ┘
Joins     ├ ┤ ┬ ┴ ┼      Arrows    ▶ ◀ ▲ ▼  →  ←  ↑  ↓  ⇄  ↔
Doubles   ═ ║ ╔ ╗ ╚ ╝    Markers   ● ○ ◆ ▪ ✓ ✗  ①②③  ╱ ╲
Blocks    █ ▓ ▒ ░  ▏▎▍▌▋▊▉
```

**Fall back to pure ASCII** (`+ - | / \ > < v ^`) only when the user asks for "plain
ASCII", or when the diagram is destined for somewhere Unicode may break — a log
line, a code comment, a `.txt` the user will paste into an old system. When in
doubt, ask; otherwise prefer Unicode.

## Pacing: slides vs. one diagram

Adapt to the concept's shape:

- **A process, flow, or anything that unfolds in steps → numbered slides.** Break it
  into 2–5 slides, each a focused diagram plus a one-line caption, so understanding
  builds. This mirrors how you'd present at a whiteboard: reveal one idea, then the
  next. Use a slide header so the pacing is visible:

  ```
  ── Slide 2/4 ─ The cache check ──────────────
  ```

- **A single structure, layout, or relationship → one annotated diagram.** Draw it
  once, well, and use callout markers (①②③) keyed to a short legend beneath. Don't
  fragment something that's meant to be seen whole.

If the topic is small, one diagram is plenty — don't manufacture slides for a
two-box idea. Match the ceremony to the concept.

## Craft rules that make diagrams readable

These are where most terminal diagrams fail. They're worth the care:

- **Alignment is the whole game.** Boxes, arrows, and columns must line up
  character-for-character. Pad with spaces so edges are flush. A diagram with ragged
  edges reads as broken even when the content is right.
- **Anchor every vertical to a fixed column — this is the #1 thing that breaks.**
  Each box wall and lifeline (`│`) must stay at the *same* column on every row it
  appears. The classic failure: an arrow runs into a wall (`──▶│`), you lose track of
  the column, and on the next rows the `│` and the `▼` below it drift one space right
  per line. The diagram looks subtly "indented wrong." To prevent it: decide the
  column positions of your verticals *first*, then build each row to hit exactly those
  columns. When an arrow meets a wall, keep the wall character in its column and let
  the arrow stop one space short (`──▶ │` reads fine and won't shove the wall). Before
  you finish, scan down each vertical and confirm it's a straight line.
- **For back-and-forth between actors, reach for the sequence template** (fixed
  vertical lifelines, time flowing down — see `references/patterns.md`) rather than
  redrawing floating boxes on every step. Fixed lifelines are far easier to keep
  aligned than boxes that move around, which is precisely where multi-step flows tend
  to drift.
- **Label the arrows, not just the boxes.** `──HTTP──▶` teaches more than a bare
  arrow. The relationships are usually the interesting part.
- **Give boxes breathing room.** One space of padding inside box walls
  (`│ Server │`, not `│Server│`) reads much cleaner.
- **One diagram, one idea.** If you're cramming six concepts into one picture, that's
  a sign to split into slides instead.
- **Keep it within 76 columns.** Terminals wrap around 80, and a single wrapped line
  destroys the alignment of everything below it. 76 leaves a safety margin — treat it
  as a real ceiling, not a suggestion, and if a diagram won't fit, split it into
  slides rather than letting it run wide.

## Saving to a file

Default is inline-only. If — and only if — the user explicitly asks to save, export,
or write the diagram to a file:

- **`.md`** when they want it in a document or README: wrap each diagram in a
  fenced ```` ```text ```` block so it stays monospace, keep the captions as prose.
- **`.txt`** when they want the raw art: just the diagrams and minimal labels, no
  markdown syntax.

Confirm the path if they didn't give one, then write it.

## Worked examples

**Example 1 — a flow, shown as one annotated diagram:**

```
        ┌──────────┐   ①GET /page    ┌──────────┐
        │ Browser  │ ───────────────▶ │  Server  │
        └──────────┘                  └────┬─────┘
              ▲                             │ ②query
              │      ③HTML (cached)         ▼
              │                        ┌──────────┐
              └──────────────────────  │   Cache  │
                                       └──────────┘
  ① request   ② miss → hit datastore   ③ response flows back
```

**Example 2 — a hierarchy, shown as a tree:**

```
  RootController
  ├─ AuthMiddleware      ← runs first, gates everything
  ├─ Router
  │  ├─ /users  ──▶ UsersHandler
  │  └─ /orders ──▶ OrdersHandler
  └─ ErrorBoundary       ← catches anything thrown above
```

**Example 3 — a comparison, shown side by side:**

```
        Monolith                    Microservices
  ┌────────────────────┐      ┌──────┐ ┌──────┐ ┌──────┐
  │  UI · API · DB ·   │      │ Auth │ │ Cart │ │ Pay  │
  │  Auth · Billing    │      └──┬───┘ └──┬───┘ └──┬───┘
  │  (one deploy)      │         └────────┼────────┘
  └────────────────────┘              message bus
   simpler, scales as one      independent, more moving parts
```

## When you need more patterns

For a fuller cookbook — sequence/timeline diagrams, state machines, layered stacks,
grids and tables, progress/gauge bars, network topologies, and more box-drawing
recipes — read `references/patterns.md`. Pull it in when the concept doesn't fit one
of the shapes above, rather than forcing it into a box-and-arrow sketch.