dot-quality

name	dot-quality
description	Use when enforcing quality standards on DOT diagrams — checking completeness, structure, and visual clarity before sharing or committing

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 cluster_legend subgraph documents all colors used
• Error and exception paths are drawn (not just the happy path)
• External dependencies are shown, even if simplified

Nice to Have — INFO

• fontname is set consistently (Helvetica or similar sans-serif)
• nodesep and ranksep are tuned for readability
• Cluster fill colors are distinct from node fill colors
• A // comment explains any non-obvious structural choice

---

Line Count Targets

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

Diagrams that exceed WARN thresholds should be split into overview + detail files.

---

Anti-Pattern Red Flags

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 Vocabulary Compliance

Shapes carry semantic meaning. Using the wrong shape creates ambiguity:

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

---

The Quality Gate

Run this 7-step check before every diagram is shared, committed, or embedded in documentation:

1. Render check — dot -Tsvg diagram.dot > /dev/null — zero errors
2. Title check — grep 'label=' diagram.dot shows a non-empty title
3. Color check — if any fillcolor or color attribute is set, cluster_legend exists
4. Shape check — review each node shape against the Shape Vocabulary table
5. Float check — every node has at least one edge (incoming or outgoing)
6. Path check — error/failure paths are present, not just the happy path
7. Size check — line count is within target range for the diagram type