SKILL.md

DOT Quality Standards

Overview

Every DOT diagram makes structural claims. Those claims must be verifiable, complete, and unambiguous. Quality enforcement ensures diagrams communicate correctly — not just render correctly.

Core principle: A diagram that renders without errors can still be wrong. Structural claims require titles, color requires legends, and shapes must match their semantic meaning.

The Iron Law

NO DIAGRAM WITHOUT A TITLE, NO COLOR WITHOUT A LEGEND

These are not suggestions. A diagram without a title is anonymous — reviewers cannot reference it. A diagram with unexplained color is ambiguous — different readers draw different conclusions.

Quality Checklist

Must Have — FAIL if missing

Graph has a label= attribute set to a meaningful title
labelloc=t is set (title appears at top, not bottom)
Every node has either a meaningful ID or an explicit label=
All edges convey accurate relationships (not aspirational or assumed)

Should Have — WARN if missing

rankdir is set explicitly (LR, TB, BT, or RL) — don't rely on defaults
Default node and edge attributes are declared at the top with node [...] and edge [...]
Shape vocabulary is consistent with the shape-meaning table below
If any color is used, a subgraph documents all colors used

Diagram Type	Target	WARN at	FAIL at
Overview / context	30–80	120	200
Architecture (detail)	80–150	250	400
Inline (single concept)	10–30	50	80
Quick sketch	5–20	35	60

Flag	Problem	Fix
Floating node	Node with no edges — forgotten or placeholder	Connect it or remove it
Mystery color	Color used without legend entry	Add to legend or remove color
`label=""`	Empty label — invisible node	Set a meaningful label
Duplicate node IDs	Same ID used for different concepts	Rename to make IDs unique
All nodes same shape	Shape vocabulary not being used	Apply shape-meaning table
Edges without direction meaning	Arrow direction doesn't match data/control flow	Reverse or relabel edges
No title	Anonymous diagram — cannot be referenced	Add `label=` and `labelloc=t`

Shape	Meaning	Misuse to Avoid
`box` / `rectangle`	Service, process, component	Don't use for data stores
`cylinder`	Database, file store, queue	Don't use for services
`diamond`	Decision point, branch	Don't use for processes
`ellipse`	Start / end state, terminal	Don't use for services
`doublecircle`	Final/accepted state (FSM)	Reserve for state machines
`parallelogram`	External system, I/O	Don't use for internal services
`note`	Annotation, documentation node	Don't use for primary components
`component`	Fan-out / fan-in coordinator	Don't use for simple steps
`point`	Initial state marker (FSM)	Reserve for state machines only
`folder`	File group, repository	Don't use for services

dot-quality

Summary

SKILL.md

DOT Quality Standards

Overview

The Iron Law

Quality Checklist

Must Have — FAIL if missing

Should Have — WARN if missing

Nice to Have — INFO

Line Count Targets

Anti-Pattern Red Flags

Shape Vocabulary Compliance

The Quality Gate

Related skills