visual-planninglisted

# Visual Planning with Mermaid Diagrams When planning non-trivial work, **use Mermaid diagrams whenever they communicate structure, flow, or relationships more clearly than prose.** Don't diagram for the sake of diagramming - use diagrams when they earn their keep. ## When to Diagram - **Architecture & component relationships** - what depends on what, how things connect - **Sequences of interactions** - API calls, user flows, event chains, multi-step processes - **Data models & entity relationships** - schemas, table relationships, domain models - **State machines & decision logic** - status transitions, branching workflows - **Class/module structure** - inheritance hierarchies, interface contracts, module boundaries If it takes more than a paragraph of prose to explain the structure and you keep wanting to say "and then" or "which connects to," or "if ...," it should be a diagram. ## Choosing the Right Diagram Type Pick the diagram type that matches what you're communicating: | What you're showing | Diagram type | Mermaid syntax | |---|---|---| | Component dependencies, system topology, task breakdowns | **Flowchart** | `graph TD` or `graph LR` | | Request/response flows, API call sequences, multi-actor interactions | **Sequence diagram** | `sequenceDiagram` | | Database schemas, domain models, data relationships | **ER diagram** | `erDiagram` | | Inheritance, interfaces, module contracts | **Class diagram** | `classDiagram` | | Status lifecycles, workflow states | **