# apt:diagram — design-discipline appendix

Loaded into `apt:diagram`'s reasoning context when the skill is invoked
with `--depth=comprehensive`. Aperant-authored — not a verbatim port. The
goal: emit a diagram that earns its space on the page, not a free-floating
box graph that "looks like a diagram."

This appendix is a posture loader. It does not change the IR. It changes
what the agent decides to put *in* the IR.

## Visual pattern library

Excalidraw exposes rectangles, ellipses, diamonds, arrows, text, and
free-form shapes. When you have a choice, the shape should encode
information the label can't:

- **Rectangle** — a unit of work, a service, a process, a system
  component. Default for "this is a thing that exists." The boring,
  honest shape.
- **Ellipse** — a state, a phase, a "moment in time." Use when the noun
  is more like a place a flow visits than a thing that owns state.
- **Diamond** — a decision point, a branching condition. If the
  outgoing arrows have different semantics ("yes" / "no" / "retry"),
  the source should be a diamond.

v2 only emits rectangles. The IR has no `shape` field on `DiagramNode`,
and `renderToFile` hard-codes rectangle elements. The choice above is
informational — it tells you *what richer shapes would mean* so you can
note the missing semantics in the diagram's accompanying prose if a
node really wants to be a diamond. Richer shapes are scheduled for v3.

## Isomorphism test

The diagram should be *the same shape* as the thing it depicts.

If the system has three layers (edge / app / data), the diagram has
three visually-distinct horizontal zones. If the system has a single
hub that talks to four leaves, the diagram has a single central node
with four spokes — not five nodes in a line.

Concretely:

- Count the "structural axes" in the thing being depicted. Layers?
  Phases? Owners? Each axis should map to a visual axis (vertical /
  horizontal / radial) in the diagram.
- If you cannot draw the structural axis, the diagram is lying. Either
  add the missing axis or admit you're depicting a different thing.
- Symmetry in the system should appear as symmetry in the layout.
  Asymmetry is a flag — either it's load-bearing (good — show it) or
  it's noise (bad — fix it).

The `validateStructure` validator codifies one slice of this: it checks
that nodes occupy the top / middle / bottom thirds of the canvas in
roughly the expected counts. That's a weak proxy — the real check is in
your eyes.

## Depth assessment

Every diagram answers one of two questions: **what** or **what + how**.

- A **what** diagram shows the inventory of things and the connections
  between them. "These are the services. They talk to each other."
  v2 targets this depth.
- A **what + how** diagram additionally encodes the protocol on each
  connection — request shape, retry policy, idempotency key, transport.
  This often requires labels on every edge, sub-groups around clusters
  of services, and sometimes a second pass at a different zoom level.
  v2 does not target this. The IR has no edge-protocol field.

Before generating the scene, decide which question the diagram answers.
If the user prompt implies "what + how" and you can only render "what,"
say so in the chat so the user knows they're getting the shallower
picture.

## Multi-zoom architecture

A real system has multiple zoom levels:

- **Far zoom** — one diagram showing the 4-7 top-level components and
  their primary connections. Fits on a slide.
- **Mid zoom** — one diagram per top-level component, showing its
  internal modules. 4-7 boxes each, again.
- **Near zoom** — one diagram per critical interface, showing the
  protocol/sequence.

v2 generates one diagram per `apt:diagram` invocation. If a user prompt
implies a multi-zoom set ("system architecture for the auth flow,"
where "the auth flow" is itself worth a deeper drawing), the agent
should:

1. Generate the far-zoom diagram for v2.
2. State in the chat that a mid-zoom diagram for the named subsystem
   would be a natural follow-up.
3. NOT chain a second `renderToFile` call automatically.

The default is one diagram per prompt. Multi-zoom orchestration is a
v3 problem.
