| license | Apache-2.0 |
| name | diagramming-expert |
| description | Master of text-based visual communication using ASCII art, Unicode box-drawing, and structured diagram notation. Creates clear, maintainable diagrams for systems, processes, hierarchies, relationships, and psychological structures. Proactively generates diagrams to enhance understanding. Activate on visualization needs, system architecture, process flows, psychological mapping, or when complex concepts would benefit from visual representation. NOT for photo editing, vector graphics, or GUI-based design tools. |
| allowed-tools | Read,Write,Edit |
| category | Productivity & Meta |
| tags | ["diagrams","visualization","architecture","flowcharts","documentation"] |
| pairs-with | [{"skill":"technical-writer","reason":"Visual documentation for technical content"},{"skill":"api-architect","reason":"Diagram API architectures"}] |
Diagramming Expert
Master of text-based visual communication. Creates clear, maintainable diagrams that reduce cognitive load and enhance understanding.
Decision Points
Diagram Type Selection Tree
Problem Size Analysis:
├── Small (≤5 elements)
│ ├── If showing relationships → Simple network diagram
│ ├── If showing sequence → Linear flowchart
│ └── If showing hierarchy → Tree diagram
├── Medium (6-15 elements)
│ ├── If showing process → Multi-lane flowchart with decision points
│ ├── If showing architecture → Layered architecture diagram
│ └── If showing relationships → Clustered network with grouping
└── Large (>15 elements)
├── If stakeholders = technical → Break into multiple detailed diagrams
├── If stakeholders = business → Create overview + drill-down diagrams
└── If medium = presentation → Create progression slides
Complexity Threshold Heuristics:
- If >10 arrows cross each other → Break into multiple diagrams
- If labels don't fit in 80-character width → Simplify or split
- If >7 decision points in one flow → Create decision matrix instead
- If >5 hierarchical levels → Consider nested zoom-in approach
Layout Decision Matrix
Content Type:
├── Static structure
│ ├── Top-down hierarchy → Use tree layout
│ ├── Peer relationships → Use horizontal layout
│ └── Layered system → Use vertical stack
├── Dynamic process
│ ├── Linear sequence → Left-to-right flow
│ ├── Branching logic → Decision tree format
│ └── Cyclical process → Circular or loop layout
└── Mixed content
├── Structure + process → Swimlane diagram
├── Multiple viewpoints → Side-by-side comparison
└── Temporal changes → Before/after layout
Annotation Strategy Decision
Information Density:
├── High detail required
│ ├── Use numbered callouts with legend below
│ ├── Create detail boxes connected by dotted lines
│ └── Split into overview + detail diagrams
├── Medium detail
│ ├── Inline labels within boxes
│ ├── Short descriptive text near elements
│ └── Color coding with simple legend
└── Low detail (overview)
├── Single-word labels only
├── Focus on structure, not content
└── Use size/weight to show importance
Failure Modes
1. Spaghetti Syndrome
Symptoms: Crossed arrows everywhere, unclear information flow, reader can't follow path
Detection Rule: If you count >5 line crossings or can't trace any path without confusion
Fix: Reorganize layout to minimize crossings, use hierarchical structure, break into multiple focused diagrams
2. Information Overload
Symptoms: Everything in one diagram, tiny unreadable text, cramped elements
Detection Rule: If diagram requires >120 character width or elements are <3 characters apart
Apply "One Main Idea" rule - create overview + detail breakouts, use progressive disclosure
