Diagram Generator

---
name: diagram-generator
description: generate, refine, validate, and render diagrams from natural language, notes, code snippets, schemas, tables, or existing diagram source. use for flowcharts, swimlanes, sequence diagrams, state diagrams, er diagrams, class diagrams, architecture/c4-style diagrams, dependency graphs, gantt charts, mind maps, user journeys, sankey-style flows, org charts, network graphs, and other visual models. supports mermaid by default, graphviz dot for complex graph layout, plantuml for uml-heavy engineering diagrams, and svg output when direct markup is more reliable.
---

# Diagram Generator

## ACTION REQUIRED (execute immediately after reading)

1. `NOW`: Confirm whether the current task falls within this skill's scope
2. `NOW`: Read `../tool-index.md` to verify tool availability and actual paths
3. `NEXT`: If a tool is missing, invoke bootstrap — do not guess paths
4. `ACT`: Enter the first step of the "Workflow" and execute — do not stop at the confirmation stage

## Purpose

Create clear, editable diagrams from messy or structured inputs. Prefer text-based diagram source first so the result can be reviewed, versioned, and refined. Render to files only when the user asks for an image/PDF or when a downloadable artifact would materially help.

## Default workflow

1. Identify the user's intent, audience, and source material.
2. Choose the diagram family and language using the decision table below.
3. Normalize entities, relationships, labels, states, branches, and time/order information before writing diagram code.
4. Generate concise, readable diagram source.
5. Validate the syntax mentally and, when creating files, run `scripts/render_diagram.py`.
6. Return the diagram source plus a short note about assumptions. When files are generated, include links to the output files.

Do not over-ask for clarification. If the request is underspecified, make reasonable assumptions and label them briefly.

## Diagram language decision table

Use Mermaid unless another language is clearly better.

| User wants | Prefer | Why |
|---|---|---|
| process flow, decision tree, simple swimlane | Mermaid flowchart | readable and easy to paste into Markdown |
| sequence of system/user interactions | Mermaid sequenceDiagram or PlantUML sequence | Mermaid for docs; PlantUML for UML formality |
| lifecycle, state machine, transitions | Mermaid stateDiagram-v2 or PlantUML state | compact transition syntax |
| database schema, entities, relationships | Mermaid erDiagram | portable ER notation |
| class/interface/object model | Mermaid classDiagram or PlantUML class | Mermaid for docs; PlantUML for detailed UML |
| project schedule | Mermaid gantt | concise timeline syntax |
| hierarchy, ideas, notes | Mermaid mindmap | good default for idea maps |
| customer/product journey | Mermaid journey | built-in journey notation |
| git history | Mermaid gitGraph | built-in git notation |
| dependency graph, package graph, large network | Graphviz DOT | better layout engines for dense graphs |
| architecture with layers, clusters, boundaries | Mermaid flowchart with subgraphs, Graphviz clusters, or PlantUML C4-style | choose based on requested fidelity |
| weighted flow/sankey-like relationship | Mermaid sankey-beta when supported, otherwise SVG or Graphviz | Mermaid support may vary by renderer |
| custom visual where source languages fit poorly | SVG | precise control over layout and styling |

## Output policy

- Always provide editable source unless the user explicitly asks only for an image.
- Default to a single best diagram. Offer alternatives only when genuinely useful.
- Prefer stable, simple syntax over fancy features that may not render in older Mermaid/PlantUML versions.
- Use short labels. Split long text into notes outside the diagram when needed.
- Avoid ambiguous node IDs. Use ASCII IDs and human-readable labels.
- Preserve user terminology, but standardize capitalization within a diagram.
- For technical diagrams, include boundaries such as client, service, database, queue, external API, and operator/user when they are implied.
- For business-process diagrams, distinguish happy path, decision points, failures, retries, and manual steps when present.
- For diagrams created from uncertain text, include an `Assumptions` section after the code.

## Mermaid generation rules

Consult `references/diagram-patterns.md` for compact templates.

General Mermaid rules:
- Start with the correct diagram directive, for example `flowchart TD`, `sequenceDiagram`, `erDiagram`, `gantt`, `mindmap`, or `journey`.
- For flowcharts, use `flowchart TD` unless the user asks for left-to-right; use `flowchart LR` for architecture and pipelines.
- Use subgraphs for swimlanes or architecture layers. Name subgraphs with readable labels.
- Keep node IDs stable and ASCII-only, for example `ingest_service[Ingest Service]`.
- Quote labels that contain punctuation likely to confuse the parser.
- Use decision diamonds for branching: `decision{Condition?}`.
- Use consistent edge labels: `-- yes -->`, `-- no -->`, `-. async .->`, or `== critical ==>` only when meaningful.
- In sequence diagrams, declare participants before messages. Use `actor` for humans and `participant` for systems.
- Use `alt/else/end`, `opt/end`, `loop/end`, and `par/and/end` blocks for conditional, optional, repeated, and parallel flows.

## Graphviz DOT generation rules

Use Graphviz for large, dense, or layout-sensitive relationship diagrams.

- Prefer `digraph G` for directed relationships and `graph G` for undirected networks.
- Set layout-friendly graph attributes at the top: `rankdir=LR`, `nodesep`, `ranksep`, and `splines=true` when helpful.
- Use `subgraph cluster_name` for boundaries and subsystems.
- Use plain labels and restrained styling.
- Use edge labels only when they add meaning.
- For many nodes, group by domain with clusters and avoid crossing-heavy all-to-all edges.

## PlantUML generation rules

Use PlantUML when the user asks for UML or needs formal UML notation.

- Wrap diagrams with `@startuml` and `@enduml`.
- Use `actor`, `participant`, `database`, `queue`, `collections`, or `component` stereotypes when useful.
- Use `package`, `rectangle`, or `node` for architecture boundaries.
- For class diagrams, include only important fields/methods unless the user asks for exhaustive detail.
- For activity diagrams, use clear start/end markers and explicit branch labels.

## SVG generation rules

Use SVG only when text diagram languages cannot express the requested visual reliably.

- Keep SVG simple, accessible, and editable.
- Include `<title>` and meaningful text labels.
- Prefer rectangles, lines, arrows, and groups over complex paths.
- Do not embed external fonts or remote images.

## Rendering files

When the user asks for PNG/SVG/PDF, create a source file and run:

```bash
python "<SKILL_ROOT>/diagram-generator/scripts/render_diagram.py" input.mmd --format svg --out output.svg
python "<SKILL_ROOT>/diagram-generator/scripts/render_diagram.py" input.dot --format png --out output.png
python "<SKILL_ROOT>/diagram-generator/scripts/render_diagram.py" input.puml --format svg --out output.svg
```

> `<SKILL_ROOT>` is the actual path of this package's `skills/` directory; the AI should detect it automatically.

The renderer is intentionally dependency-tolerant. It tries common local tools and reports actionable installation hints if a renderer is unavailable. Do not claim an image was rendered unless the script completed successfully and the output file exists.

## Validation checklist

Before finalizing:

- The diagram type matches the user's task.
- The source is syntactically plausible for the chosen language.
- Labels are short enough to fit.
- Edges and message order reflect the input accurately.
- Assumptions are called out when the input was incomplete.
- For generated files, the output exists and opens or has nonzero size.

## Common response template

Use this structure for most diagram answers:

```markdown
Here is the editable [language] version:

```[language]
[source]
```

Assumptions:
- [only if needed]

Rendered file: [link] [only if generated]
```

For English user requests, respond in English. For Chinese user requests, respond in Chinese unless they ask otherwise.

---

## On-Demand Bootstrap

### Automation capability boundaries

| Tool | Auto-installable | Install method | Notes |
|------|-----------------|----------------|-------|
| Mermaid CLI (mmdc) | ✓ | npm install -g @mermaid-js/mermaid-cli | Renders Mermaid to PNG/SVG |
| Graphviz (dot) | ✗ | Manual install | https://graphviz.org/download/ |
| PlantUML | ✗ | Requires Java + plantuml.jar | https://plantuml.com/download |
| Python (render script) | ✓ | Already included in bootstrap | `scripts/render_diagram.py` dependency |

### Notes

This skill primarily outputs text-based diagram source (Mermaid/DOT/PlantUML) and does not necessarily require local rendering tools. The corresponding renderer is needed only when the user explicitly asks for PNG/SVG/PDF files.

If a renderer is unavailable, `scripts/render_diagram.py` outputs installation hints instead of failing with an error.

---

## Routing Context

**Upstream entry**: `skills/SKILL.md` (master control), `routing.md`
**Trigger conditions**: user says "draw a diagram", "flowchart", "architecture diagram", "attack path diagram", "sequence diagram", "Mermaid", "Graphviz", "PlantUML"
**Downstream outputs**:
- Generated diagrams can be embedded in reports from `docs-generator/`
- Attack path diagrams can be used alongside penetration test reports from `pentest-tools/`

**Peer modules**: `docs-generator/` (diagrams embedded in reports)


## Task Completion Self-Check (MUST pass before claiming completion)

- [ ] Did I execute every step of the workflow (rather than just reading it)?
- [ ] Did I use real tool paths based on `tool-index`?
- [ ] Did I produce reproducible evidence (commands/scripts/screenshots/reports)?
- [ ] Did I complete and write back the Checklist items required by RULES?