A Figure in a Decision Record¶
Source: hooks/ways/documentation/adr/figure/figure.md
Frontmatter
| Field | Value |
|---|---|
description |
a decision record that carries a figure, drawing the layout, appearance, geometry, timing, flow or state it decides, embedded beside the decision it draws, redrawn with the text until acceptance, paired with the record as published, and shown to the operator as rendered PNGs or a contact sheet before the probes and before acceptance |
vocabulary |
figure picture drawing sketch illustration image svg png render rsvg-convert generator generated layout appearance geometry spacing timing looks visual palette legend shapes paired published redraw amend amendment mockup wireframe screen panel alt text caption contact sheet montage grid review revise answers findings matches mismatch stale |
files |
docs/architecture/.*/figures/ |
refire |
0.15 |
scope |
agent, subagent |
A record carries a figure when it decides something a reader sees or that a picture explains: layout, appearance, geometry, timing, flow or state. It also carries one when the operator should steer on a picture before implementation starts.
Making the figure¶
- Any picture that communicates counts. A rough hand drawing counts.
- A project that keeps a small shared visual vocabulary in one module (a palette legible in light and dark themes, shapes, line styles, a legend, type sizes) gets figures that read alike.
- Mermaid suits structure, flow and state where it is enough. The mermaid way covers it.
- A figure generated by code with a drift check is one good method. If a check exists, a mismatch on an accepted record is settled by amending the record or by leaving the figure as published. A silent redraw never settles it.
The record and its figure pair¶
A record and its figure pair together and remain as published. In the operator's words, "an adr with a related diagram probably pair together and remain as published."
- After acceptance, the figure changes only when the record is amended, in the same change as the amendment.
- A later record on the same topic may draw a very different figure.
Until acceptance, the figure follows the text¶
The text moves before acceptance: the operator answers the probes and reviewers return findings. A figure that shows anything the text no longer decides is a defect. On each change to the text:
- Check each figure against the final text. Redraw any part that no longer matches, in the same change as the text.
- Rewrite the figure's alt text and the sentence that introduces it to match.
- Render each figure to a PNG again and show the operator before acceptance.
When a subagent writes the record, the brief carries these three steps, names each figure file, and asks for the PNG paths in the return. The lead shows those PNGs to the operator.
Placement and showing¶
- Save the figure as
figures/ADR-NNN-<slug>.svgin the record's folder, committed with the record. - Embed it beside the decision item it draws, introduced by a sentence that says what it shows, with alt text that states its content.
- Before asking the probes, render the SVG to a PNG in a
figures/folder in the session scratchpad, for example withrsvg-convert, and send it to the operator. A probe about appearance names the figure. - When a record carries several figures, or several records go to the operator together, put the PNGs on one contact sheet, each labelled with its file name. With ImageMagick, where
$SCRATCHis the session scratchpad, the command ismontage -label '%f' "$SCRATCH"/figures/ADR-NNN-*.png -geometry +8+8 "$SCRATCH/ADR-NNN-sheet.png". The sheet goes outsidefigures/, so a second run does not tile the old sheet into the new one. On ImageMagick 7 without the legacy links, the command startsmagick montage. Send the sheet first and the single PNGs on request.
See Also¶
- adr(documentation) — the record format and commands for this project
- adr/consider(documentation) — handing the record to the operator; the figure is shown before the probes
- mermaid(documentation) — Mermaid for structure, flow and state, styled for both themes
- visualization(softwaredev) — when a picture explains better than prose