ADRs versus generated docs: two different jobs, one shared trap

The classic format is four fields: context, decision, consequences, status. Its defining property is immutability. You do not edit ADR-0012 when the world changes, you write ADR-0031 and mark the old one superseded. That is what makes an ADR corpus valuable years later: it is the only place the reasoning survives, including the options that were rejected and why.

Nothing in that format is derivable from source code. Why the team picked one queue over another, which constraint made the boring choice the right one, which risk was accepted knowingly: none of it is in the repository, and no generator will produce it.

The generated architecture doc has the opposite contract. It has no status field because there is only ever one version, the one matching the current commit of the tracked branch. It carries no reasoning, only what the files show: which components exist, how data moves, how the thing deploys, what lives in which directory.

It also only moves when the system moves. Each sync hashes the structure that feeds the document before regenerating anything, so a week of commits touching tests, comments, and prose leaves it untouched. When the document does change, something in the system changed, which is a signal an ADR corpus cannot give you and a wiki page never gave anyone.

That makes it useless as a record and excellent as a mirror. Read it the day you write an ADR and you get an accurate account of the starting state, which is the context field most ADRs fill in from memory.

The common failure is an ADR quietly promoted into a system description. Somebody needed the topology written down, ADR-0007 happened to contain a diagram, and now it is the only place the queue layout appears. The record is still honest about the moment it describes. Readers stop treating it that way, and the ADR that was correct on the day it was written becomes the source of a wrong belief.

The second half of the trap is a pasted image. A screenshot inside an immutable document is immutable too, which is correct for the decision and wrong for the picture. Six months later the record is right about the decision and misleading about the system.

Put state in the generated doc and reasoning in the ADR. When a decision is topological, link the ADR to the living diagram rather than pasting a still, so the record says what changed and the picture shows what exists. A live embed is one markdown line and needs no account to view, which matters because ADRs get read by people outside the team, and by people reading the repository years later.

If you want to freeze a picture next to a specific decision, export the canvas as PNG or JPEG and attach the still deliberately, with the date on it. The point is that the freeze becomes a choice rather than an accident.

Keep the ADR index in the repository where the decisions were made, and keep the generated doc regenerating on the branch. When the two disagree, that disagreement is information: either something drifted, or a decision was made that nobody recorded. Both are worth a conversation before the next design starts.

Concretely, the embed line sits in the context section, where the reader needs the starting state and where a screenshot would otherwise go.

<!-- docs/adr/0031-move-session-store-to-redis.md -->
# 31. Move the session store to Redis

Date: 2026-08-21
Status: accepted, supersedes ADR-0012

## Context

Sessions are held in the primary Postgres instance, which couples session
reads to the write path of the checkout flow. The system as it stands today:

![Platform architecture](https://datadef.io/api/embed/acme-platform-4f2c)

## Decision

...

## Consequences

...

• Keep ADRs up to date
• Generate architecture.md from a repository
• What makes documentation trustworthy
• Live embeds: one line, always current