SKILL.md
Thinking
Before drawing, DIAGNOSE:
- Mental Model Gap: What does user THINK vs what IS true? Name both.
- Primitive: Which structure captures the essence? (see Quick Pick below)
- Hierarchy: ONE main thing + 2-3 supporting details. Max 6 boxes.
- 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──▶ TREEProcess
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┌──┐)