ADR shape

An ADR in this shape reads without dates and without a separate rationale section: the first paragraph says what it closes, each decision carries its reasoning, each option carries its verdict, and the consequences say what got worse as well as better and what was deliberately left open. The split rule decides what the ADR holds: the sticky choices live in the ADR, the reversible detail lives in the architecture document under a section the ADR points at, and the two point at each other.

Two modes, chosen from the request. Write drafts a new ADR from a resolved discussion — a grill round just closed, a pasted transcript, a decision the owner states outright — or from a review note's findings; its steps are under Write. Review reads an existing ADR and reports where it departs from the shape; its steps are under Review. Either mode that touches an ADR already accepted obeys Amending.

Write

1. Gather

Read the source in full — every rejected option, every "later", every number — before writing anything. Collect, as a flat list: the decision and the reasons given for it; every option raised, with the objection that sank it or the condition it waits on; every detail the discussion settled (a name, a version, a threshold, a field list, a fallback); every open thing it left. Then find what the ADR closes — an earlier ADR's Deferred, deliberately entry, a numbered open item in the architecture document, a brief's open question — and the highest number in the ADR directory. When the source is a review note or a correction on an ADR that exists, the list holds what changed and why. For an ADR still Proposed, the write edits it in place and the steps below apply to the file as it stands. For an ADR already accepted, the write is an amendment under Amending: its destination is an Update section on that ADR, so step 3 fills that section in place of a copy of the template, step 4 moves any detail the note routed out, and step 5 ranks only what the Update decides. Done when the list holds every option and every detail from the source, the thing closed is named, and the next number is known: four digits, one past the highest existing — or, for an amendment, the ADR and today's date.

2. Route every detail

Apply the split rule to each item on the list and mark it ADR or architecture document. Apply it to each detail on its own: the choice of engine is ADR material while the bindings it uses and the worker model it runs under are usually not, and they split even though they arrived in one breath. Done when every item carries a destination.

3. Draft the ADR

Copy 0000-template.md to NNNN-<slug>.md at the next number and fill every placeholder from the routed list: