---
name: cartography
description: ASCII maps as information architecture. Spatial reasoning in text. Wake-up maps, decision trees, system diagrams.
version: 0.3
status: functional
---

# Information Cartography Skill

ASCII maps as a first-class information format.

## Why ASCII Maps

| Property | Benefit |
|----------|---------|
| **Whitespace efficient** | Negative space conveys structure for free |
| **Data-ink optimal** | Tufte principle: max information per character |
| **Token efficient** | Single tokens convey spatial relationships |
| **Claude-native** | LLMs emit ASCII art fluently (training data rich) |
| **Composable** | Build complex maps from simple primitives |
| **Zoom-ready** | Works in future fluid UIs (Gemini 3 canvas, etc.) |
| **Universal render** | Works in any terminal, markdown, transcript |

## The Insight

```
Traditional docs:  "First do X, then if Y do Z, otherwise do W"
ASCII map:         ┌─X─┐
                   │   ├─Y→Z
                   │   └─W
```

Same information. Map version:
- Scannable in O(1)
- Relationships visible
- Branching explicit
- Future Claude grasps instantly

## Primitives

### Boxes
```
┌─────────┐    ╔═════════╗    ┏━━━━━━━━━┓
│ simple  │    ║ double  ║    ┃  bold   ┃
└─────────┘    ╚═════════╝    ┗━━━━━━━━━┛
```

### Arrows & Flow
```
→ ← ↑ ↓ ↔ ↕     Direction
├ ┤ ┬ ┴ ┼       Junctions
│ ─ ┌ ┐ └ ┘     Lines/corners
▶ ◀ ▲ ▼         Emphasis
```

### Hierarchy
```
ROOT
├── child
│   ├── grandchild
│   └── grandchild
└── child
```

### Decision Trees
```
        ┌─────────┐
        │ START   │
        └────┬────┘
             │
      ┌──────┴──────┐
      ▼             ▼
   ┌─────┐      ┌─────┐
   │ YES │      │ NO  │
   └──┬──┘      └──┬──┘
      │            │
      ▼            ▼
```

### Status Indicators
```
✅ done    ⏳ pending    ❌ blocked    🔄 in progress
⚡ urgent  💡 idea       🎯 target     🐯 tiger
```

## Box Construction Rules

Getting ASCII boxes to align requires character counting. These rules prevent the most common alignment bugs.

### Rule 1: Box Width = 1 + interior + 1

```
┌─────────────────────┐   ← 1 + 21 dashes + 1 = 23 chars total
│ Content here        │   ← 1 + 21 chars content + 1 = 23 chars total
└─────────────────────┘   ← must match top exactly
```

**Every line between `│...│` must have exactly `interior` characters.** Count them. If the box top has 21 dashes, every content line must have exactly 21 visible characters between the pipes.

### Rule 2: Pad Content to Fill Interior

```
Interior = 21
"Website Build" = 13 chars
Padding needed: 21 - 1(leading space) - 13 = 7 trailing spaces

│ Website Build       │   ← 1+13+7 = 21 ✓
│  ├── HTML/CSS    ✓  │   ← 2+4+8+4+1+2 = 21 ✓
│  ├── gallery     ~  │   ← 2+4+7+5+1+2 = 21 ✓
```

For subtask lines: `2(indent) + 4(tree ├──+space) + name + padding + status(1) + 2(trailing) = interior`

### Rule 3: Bridge Lines Must Match Column Positions

When connecting a box to an adjacent column (like heat bars), the total characters after the box must equal the gap on non-bridge lines:

```
║  ┌─────────────────────┐              ████ hot topic
║  │ Header              │───────────── ███░ warm topic
║  │  ├── subtask     ✓  │              ██░░ cooling
```

If non-bridge lines have 14 spaces between `│`/`┐`/`┘` and the heat column, the bridge must also span 14 chars: `─────────────` (13 dashes) + ` ` (1 space) = 14. Not 11, not 12. Count them.

### Rule 4: Side-by-Side Boxes Need Consistent Gaps

```
┌──────────────────────┐  ┌──────────────────────┐
│ Box A (interior=21)  │  │ Box B (interior=22)  │
└──────────────────────┘  └──────────────────────┘
                        ^^
                     2-space gap
```

The gap between boxes must be identical on every line — top, content, and bottom.

### Rule 5: Status Indicators Are 1 Character

Use single-width characters only: `✓` `~` `x` `*` `?`

**Never use emoji** (✅ ⏳ ❌ 💡) in monospace ASCII art — they render at 2ch width in browsers and terminals, breaking all alignment to the right. Same for geometric shapes like `▼` (U+25BC) — use `v` instead.

### Rule 6: Verify With Character Counting

Before committing any ASCII box art, count characters on each line. A fast check:

```
Expected: │ + interior + │ = box_top_width
Actual:   count visible chars between the pipes
Match?    If not, add/remove spaces until they do
```

The most common bug: adding a character to content (longer name, extra space) without removing one elsewhere. Every character shifted right propagates misalignment through the rest of the line.

## Composition Patterns

### Wake-Up Map
Session summary + decision tree + quick reference
See: `WAKE-UP-MAP.md`

### Thread Map
Stalled work inventory with status + blockers
See: `STALLED-THREADS-MAP.md`

### Skill Map
Capability overview with commands + examples
See: Any `SKILL.md`

### Flow Map
Process/pipeline with branching paths
```
INPUT ──→ PROCESS ──┬──→ OUTPUT A
                    └──→ OUTPUT B
```

## Future: Fluid Canvas Integration

When Gemini 3 / zooming UI arrives:
- ASCII maps become zoomable regions
- Boxes expand to full content on zoom
- Arrows become navigable links
- Maps compose into larger territories

```
ZOOMED OUT:          ZOOMED IN:
┌───┐                ┌─────────────────────┐
│ A │ ──→            │ COMPONENT A         │
└───┘                │                     │
                     │ - detail 1          │
                     │ - detail 2          │
                     │ - detail 3          │
                     │                     │
                     │ [links] [actions]   │
                     └─────────────────────┘
```

## Usage

When to emit ASCII maps:
- Session summaries (what happened, what's next)
- Decision points (if X then Y)
- System architecture (components + relationships)
- Todo/status overviews (scannable progress)
- Any time structure > prose

## The Meta-Point

```
┌─────────────────────────────────────────────────────┐
│                                                     │
│   Maps are compressed spatial reasoning.           │
│   Claude thinks in tokens.                         │
│   ASCII maps are token-efficient spatial thought.  │
│                                                     │
│   Therefore: ASCII maps are Claude-native UX.      │
│                                                     │
└─────────────────────────────────────────────────────┘
```

---

*Seeded: Jan 15, 2026, 01:50, from tiger meme session*
*"The map is not the territory, but ASCII maps are pretty close"*