# SKILL — Diagram

## When to use
Only when a visual **materially improves understanding** over prose or a table. A diagram is
never decoration.

## Choose the right form
| Showing… | Use |
|----------|-----|
| A process with steps | flowchart |
| Interactions over time | sequence diagram |
| Conditional logic | decision tree |
| Connectivity / topology | network diagram |
| Hierarchy / reporting | org chart |
| Systems & boundaries | architecture diagram |
| Data structure | entity-relationship diagram (ERD) |
| Events over time | timeline |
| Exact comparison | **table** (often beats a diagram) |
| Nuance / caveats | **prose** |

## Tools by job (all free/open-source)
Full library list, install, and examples: [`../../diagram-tools.md`](../../diagram-tools.md).
Defaults:
- **Inline & simple** (renders in Markdown): **Mermaid** (MIT) — flowchart, sequence, ERD, timeline.
- **Polished cloud/infra architecture:** **`diagrams`** (MIT; needs Graphviz) — AWS/Azure/GCP/
  Kubernetes/on-prem/Cisco icons; PNG/SVG/PDF.
- **General auto-layout** (flowcharts, decision trees, org charts, dependency/process maps): **Graphviz**.
- **Editable network maps:** **N2G** → `.drawio`, so an engineer can reposition/annotate.
- **Engineering / cabling / electrical:** **schemdraw**; **rack elevations:** `rackdiag`.
- **Database / data model:** **erdantic**. **Formal UML:** PlantUML.
- **Interactive topology (HTML):** **pyvis**. **Charts / Sankey:** **plotly**; custom static: **matplotlib**.
- **Topology modeling/analysis:** **NetworkX** (model it, then render with Graphviz/N2G).

The best-tool-by-assignment table is in `../../diagram-tools.md`.

## Rendering pipeline
Source data → model (NetworkX / structured) → render (Mermaid / Graphviz / `diagrams` / N2G) →
output (SVG/PDF/PNG for documents, `.drawio` when a human must edit, interactive HTML for live
reports). Keep the diagram **source** in Git.

## Where the DATA comes from (scope boundary)
I render diagrams from data I'm **given**. Live discovery of real infrastructure — SSHing into
devices (Netmiko / NAPALM / pyATS) or querying cloud accounts (boto3 / SDKs) — is a **separate,
credential-sensitive, read-only collection step** and **not mine to do**. That gathering belongs
to Scout (authorized, read-only) or a dedicated infrastructure tool, which hands me the data. I
keep **as-designed** vs. **as-built** distinct and flag differences.

## Quality standards
- Every node, label, arrow, and relationship is intentional and traceable to the source.
- The diagram matches the written procedure/source exactly — a mismatch is an error.
- Standard, consistent symbols; readable labels; a caption; a prose/table alternative where needed.

## Limits
Conservative with meaning: a diagram re-presents a system, never redefines it. I render provided
data; I don't collect live device/cloud data and I hold no such credentials.
