DDP: Draw the Damn Picture
Purpose
Sometimes specs aren't enough. You need to see how things connect.
This skill generates Mermaid diagrams to visualize:
- •Data flows between components
- •Class hierarchies and relationships
- •System architectures
- •State machines and transitions
- •Sequence of operations
When you can't hold the mental model in your head, draw the damn picture.
When to Use
- •Understanding how data flows through a system
- •Mapping relationships between classes or modules
- •Visualizing complex control flow
- •Explaining architecture to yourself or others
- •When you keep re-reading code and it's not clicking
Invocation
/lore-development:ddp <what to visualize>
Examples
/lore-development:ddp how chat messages flow between user and AI /lore-development:ddp the inheritance hierarchy of BaseView /lore-development:ddp the request lifecycle from HTTP to database /lore-development:ddp state transitions in the order fulfillment system /lore-development:ddp how the plugin system loads and registers skills
Process
Step 1: Understand the Subject
Clarify what needs visualization:
- •What's the scope? (One feature? Whole system? Specific interaction?)
- •What's the perspective? (Data flow? Control flow? Structure?)
- •What level of detail? (High-level overview? Implementation specifics?)
Step 2: Explore the Code
Trace through the codebase to understand:
- •Entry points and exit points
- •Key actors (classes, functions, services, users)
- •Relationships (calls, extends, contains, depends on)
- •Data transformations along the way
Step 3: Choose the Right Diagram Type
| Need to Show | Diagram Type | Good For |
|---|---|---|
| Sequential interactions | sequenceDiagram | API calls, message passing, request/response |
| Class relationships | classDiagram | Inheritance, composition, dependencies |
| System structure | graph / flowchart | Components, modules, architecture |
| State changes | stateDiagram-v2 | Workflows, lifecycles, FSMs |
| Data flow | flowchart | Pipelines, transformations |
| Entity relationships | erDiagram | Data models, database schemas |
Step 4: Draw the Picture
Create a Mermaid diagram that:
- •Shows the essential relationships (not every detail)
- •Uses clear labels
- •Groups related items when helpful
- •Includes a legend if notation isn't obvious
Step 5: Annotate
Add context around the diagram:
- •What triggered this visualization
- •Key insights revealed by the picture
- •Things that aren't captured in the diagram
- •Questions that emerged
Output
Save to .lore/diagrams/[subject].md
Use kebab-case. Be descriptive (e.g., chat-message-flow.md, view-class-hierarchy.md).
Document Structure
Before writing: Load ${CLAUDE_PLUGIN_ROOT}/shared/frontmatter-schema.md to get frontmatter field definitions and status values for diagrams.
--- [frontmatter per schema] --- # Diagram: [Subject] ## Context What prompted this visualization. What question are we answering? ## Diagram ```mermaid [diagram code]
Reading the Diagram
Explanation of what the diagram shows. Call out non-obvious elements.
Key Insights
What becomes clear when you see it visually:
- •Insight 1
- •Insight 2
Not Shown
Important aspects not captured in this view:
- •Error paths
- •Edge cases
- •Implementation details
- •etc.
Related
Links to specs, other diagrams, or code that provides more context.
## Additional Resources ### Reference Files For Mermaid syntax patterns and diagram examples, consult: - **`references/mermaid-patterns.md`** - Flow, structure, architecture, and lifecycle diagram patterns with tips ## Context Check `.lore/specs/` for feature documentation that might need visualization. Check `.lore/brainstorm/` for ideas that might benefit from a picture. ## Specialized Agents If `.lore/lore-agents.md` exists, consult it for specialized agents that can help identify what needs visualization. Architecture agents can highlight complex relationships worth diagramming. Invoke relevant agents via Task tool and incorporate their insights.