# readable-diagrams

_Diagrams a newcomer can read, proved by readers._

> Source: https://fullstack.rocks/skills/readable-diagrams
> Code: https://github.com/Fullstack-Rocks/skills/tree/main/skills/readable-diagrams

You’ve probably seen this diagram. Lines cross, arrows run through boxes, and the one fact you need lives in a side note in the corner. Whoever drew it can read it, but a new engineer can’t.

**readable-diagrams builds diagrams a newcomer can read, and proves it.** The agent asks which tool to draw in (draw.io, Mermaid, D2, PlantUML, Graphviz, Excalidraw or the project’s own), builds one story per page from facts checked against your code, and runs every page through a geometry checker. Then three fresh reviewer agents answer checked questions from the images alone and score them.

**Install**

Claude Code:

```shell
npx skills add Fullstack-Rocks/skills --skill readable-diagrams -a claude-code
```

Codex:

```shell
npx skills add Fullstack-Rocks/skills --skill readable-diagrams -a codex
```

Cursor:

```shell
npx skills add Fullstack-Rocks/skills --skill readable-diagrams -a cursor
```

Any agent:

```shell
npx skills add Fullstack-Rocks/skills --skill readable-diagrams
```

Prompt, to paste into your agent:

> Install the readable-diagrams skill from https://github.com/Fullstack-Rocks/skills by running npx skills add Fullstack-Rocks/skills --skill readable-diagrams, then use it whenever you draw or redraw an architecture, network, sequence or pipeline diagram.

`readable-diagrams` stands alone and needs none of the other skills. Its scripts need Python 3.10+ and use only the standard library.

**Try saying**

- Draw our AWS network so a new engineer can follow it.
- Draw our deploy pipeline so a new engineer can explain it.
- This diagram’s lines go over each other. Make it readable.

## How does it work?

A diagram is **readable** when an engineer new to the system can answer concrete questions about it from the picture alone, and explain it afterwards. The agent gets there in six steps:

1. **Choose the tool.** The agent asks which tool to draw in, offering the ones it can both write and render to PNG plus whatever the project already uses, and renders one test file before it starts.
2. **Gather the facts and the questions.** It reads the source of truth first and writes a fact list, every component and every relationship with caller, callee, protocol, port and source location, and a question bank of 2 or 3 checked questions per page, with at least one “why” or “what happens when X fails” question.
3. **Plan pages and the decisions log.** One story per page, each with a form: topology, sequence, lanes, inventory table or overview map. The style choices are fixed in a decisions log before round 1, so reviewers don’t flip each other’s preferences.
4. **Build and check.** Every page goes through `scripts/check_diagram.py`: crossing lines, lines through shapes or text, U-shaped and detouring arrows, labels on bends or borders, small text, pages too wide, steps out of reading order, repeated or referenced but not drawn, legend rows used or unused. Then the agent answers the question bank from its own renders, so a fact that lives only in a side note is moved onto its step.
5. **Review rounds.** Three fresh reviewer agents answer the checked questions from the images alone and score readability and understanding. `scripts/score_round.py` gates on the median: 8.5, or 8.0 when no reviewer flags a problem that blocks understanding. A page that passes is frozen, and a page that stops improving for two rounds changes its form instead of getting polished. Eight rounds at most.
6. **Deliver.** The diagram source, the PNGs and the generator, if there is one, get committed, with the score table per round and page and any fact the source left undefined.

Why a floor of 8.0? Pages settle between 8.0 and 8.5, and one reviewer’s score on an unchanged page moves by about ±0.5, so a bare 8.5 bar passes or fails them by chance. Correct answers with nothing blocking are the evidence that matters.

For draw.io, `scripts/drawio_export.py` renders each page and exports its geometry straight from the draw.io viewer. The checker reads plain geometry JSON, so it works with any tool.

The layout rules come from 40+ scored rounds on four AWS architecture diagrams. What moved scores was structure (one story per page, lanes, sequence frames, one meaning per mark), rarely polish.

```mermaid
flowchart TD
  T[Choose the tool] --> F[Fact list + question bank<br/>checked against the source]
  F --> P[One story per page<br/>decisions log]
  P --> B[Build and render until<br/>check_diagram.py says OK]
  B --> R[Round: 3 fresh reviewers<br/>images only]
  R --> G{score_round.py<br/>median 8.5, or 8.0<br/>when nothing blocks}
  G -->|passes| D[Deliver: source, PNGs,<br/>score table]:::hi
  G -->|fails, fix and rebuild| B
  classDef hi fill:var(--highlight),stroke:var(--highlight),color:var(--on-highlight)
```

_A page passes when fresh reviewers answer from the image alone, not when it looks tidy._

## The other skills

**The other skills**

- [under-engineering](https://fullstack.rocks/skills/under-engineering)
- [um-maybe](https://fullstack.rocks/skills/um-maybe)
- [under-engineering-review](https://fullstack.rocks/skills/under-engineering-review)
- [call-depth](https://fullstack.rocks/skills/call-depth)
- [code-standards](https://fullstack.rocks/skills/code-standards)
- [delegate](https://fullstack.rocks/skills/delegate)