Diagramming

Create one diagram per idea. Favor accurate structure and readable labels over decorative complexity.

Workflow

1. Identify the relationship the reader needs to see: sequence, branching, state, hierarchy, ownership, data transformation, entity relation, or time.
2. Choose the smallest fitting diagram using references/diagram-types.md.
3. Reduce the content to essential nodes, meaningful edges, and explicit boundaries.
4. Write Mermaid source by default. Use the user's requested format when specified.
5. Label decision branches, error paths, important data shapes, and transition triggers.
6. Validate with an available local Mermaid backend. If none exists, run the manual checks in references/validation.md and describe the result as “syntax reviewed,” not “validated.”
7. Inspect the rendered image when rendering is available. Correct clipping, overlap, tiny text, excessive crossings, or misleading layout.
8. Deliver the editable source, a one- or two-sentence caption, and rendered files when requested.

Backend selection

Use an already-installed maintained Mermaid skill, mmdc, or compatible local renderer when available. A maintained upstream skill may own parsing, retry, rendering, and visual QA; retain responsibility for factual content and diagram scope.

Do not install Node packages or call a remote renderer merely because this skill triggered. Remote rendering may disclose diagram content. Ask before installing dependencies or sending content to Kroki or another service.

When no renderer exists, Mermaid source is still a complete deliverable.

Readability rules

• One diagram, one main idea. Split an overview from details when necessary.
• Prefer left-to-right for pipelines and top-to-bottom for branching processes.
• Keep node labels short; move explanation into the caption.
• Give stable, meaningful node IDs and quote labels containing punctuation.
• Use subgraphs only for real boundaries such as services, teams, trust zones, or phases.
• Show return messages in sequences and loop-back edges in iterative flows.
• Use consistent shapes for input/output, process, decision, datastore, and terminal nodes.
• Use one accent class for the critical path or error path; avoid rainbow styling.
• Do not encode meaning by color alone.
• Do not invent components or relationships to make a diagram look complete.

Delivery

• Chat request — provide a fenced mermaid block plus caption.
• Reusable artifact — write .mmd and optionally SVG/PNG/PDF if a renderer is available.
• Documentation — embed Mermaid in the relevant Markdown file and keep source paths or evidence notes nearby.
• Unsupported Mermaid shape — use a simple SVG, HTML, ASCII diagram, or recommend a more suitable tool rather than forcing unreadable Mermaid.

Quality gate

• The declared diagram type matches the syntax.
• Every node and relationship reflects inspected or supplied information.
• Every decision has labeled outgoing branches.
• Success, failure, and loop paths are not silently omitted.
• Direction, grouping, and cardinality communicate the intended meaning.
• The caption says what the reader should notice.
• The final response distinguishes rendered validation from manual syntax review.