ascii-explainer

## Thinking

Before drawing, DIAGNOSE:
1. **Mental Model Gap**: What does user THINK vs what IS true? Name both.
2. **Primitive**: Which structure captures the essence? (see Quick Pick below)
3. **Hierarchy**: ONE main thing + 2-3 supporting details. Max 6 boxes.
4. **Verify**: Can diagram be understood WITHOUT surrounding text?

**CRITICAL**: Diagnosis IS the skill. Surfacing "user assumes X, but actually Y" is the value—not drawing boxes.

---

## Quick Pick (90% of cases)

| If the concept has... | Use | ASCII Pattern |
|-----------------------|-----|---------------|
| Steps in order | **DAG** | `A → B → C` |
| States + events | **State Machine** | `[S1] --evt--> [S2]` |
| Parent-child hierarchy | **Tree** | `Root` with `/` `\` branches |
| Cycles/feedback | **Graph** | Arrows that loop back |
| Stages that transform | **Pipeline** | `[Stage1] ──▶ [Stage2]` |
| 2D relationships | **Matrix** | Grid with `┌─┬─┐` |

For full primitive taxonomy → see `PRIMITIVES.md`

---

## Primitive Selection Flowchart

```
Continuous (infinite states)? ──Yes──▶ MANIFOLD
         │No
Time/order focused? ──Yes──▶ SEQUENCE│QUEUE│STACK│PIPELINE│TIMELINE
         │No
Concurrent states? ──Yes──▶ PETRI NET
         │No
States + transitions? ──Yes──▶ STATE MACHINE
         │No
Two distinct node types? ──Yes──▶ BIPARTITE
         │No
Edges connect 3+ nodes? ──Yes──▶ HYPERGRAPH
         │No
Partial ordering? ──Yes──▶ LATTICE
         │No
Spatial cells? ──Yes──▶ GRID
         │No
N-dimensional? ──Yes──▶ TENSOR/MATRIX
         │No
Direction matters? ──No──▶ UNDIRECTED GRAPH
         │Yes
Can loop back? ──Yes──▶ CYCLIC GRAPH
         │No
Multiple parents? ──Yes──▶ DAG
         │No──▶ TREE
```

---

## Process

### 1. Clarify (1 question max)
- What are the "things"? (nodes/states/events)
- What are the "connections"? (edges/transitions/order)
- Can you loop back?

If obvious, skip.

### 2. Identify Primitive
Use Quick Pick or flowchart. State: "This is a [PRIMITIVE] because [ONE REASON]."

### 3. Render ASCII
- Max 20 lines
- Use: `─ │ ┌ ┐ └ ┘ ├ ┤ ┬ ┴ ┼ ← → ↑ ↓ ● ○ █`
- Label with user's domain terms

### 4. Verify
"Does this capture the structure? What's missing?"

---

## Output Structure

```
[1-line context]

┌─────────────────────────────────────┐
│     WHAT [USER/ISSUE] ASSUMES:      │
├─────────────────────────────────────┤
│  [Their mental model]               │
└─────────────────────────────────────┘

┌─────────────────────────────────────┐
│          ACTUAL STATE:              │
├─────────────────────────────────────┤
│  [Reality]                          │
│     ↑ key difference                │
└─────────────────────────────────────┘

Primitive: [NAME] — "[reason]"

[ASCII DIAGRAM]

┌─────────┬────────────┬─────────────┐
│ Aspect  │  Assumed   │   Actual    │
├─────────┼────────────┼─────────────┤
│ X       │ state A    │  state B    │
└─────────┴────────────┴─────────────┘

★ Insight ─────────────────────────────
[Transferable lesson]
───────────────────────────────────────
```

---

## Constraints

- Emoji sparingly: 🟣🔵🟢 for state, ✓✗⚠️ for status
- Nested concepts: 3-space indent
- Pointer annotations: `↑` or `←` with 1-line labels
- Never: prose paragraphs first, box soup, mixed styles (`+--+` with `┌──┐`)