A proposed ADR is not a decision
Teams under pressure to "document architecture" often open an ADR template, fill Context and Alternatives, and leave Status as Proposed. That feels like governance. It is not a decision yet. A proposed ADR is a draft of a choice — useful for review, useless as a constraint — until someone accepts it, names who owns the consequence, and says what would force a revisit. We have seen BuilderHelp platform seams, Sanity content models, and Endeo offline paths stalled the same way: the folder grew while the code kept guessing.
Draft and decide are different verbs
An ADR earns its keep when it captures a significant choice the code cannot express: which system owns the order record, whether the field app shares a session with the dashboard, how refusal paths behave when OCR confidence is low. The template is a container for that choice. Filling the container is drafting.
Deciding means Status moves out of Proposed. Accepted (or Rejected, or Superseded later) is the line that tells a future reader — human or agent — whether the constraint is live. A Proposed file sitting next to Accepted ones trains people to treat the whole directory as optional commentary.
We see the blur in consulting reviews. Someone points at docs/adr/0007-proposed-catalog-store.md and says the decision is already written. The PR that ships a second write path disagrees. The document never claimed authority; the status still said open for comment.
Proposed is a review state, not a parking lot
Proposed should mean: the options are on the page, trade-offs are visible, and a named review will close it. Time-box that review the same way you time-box a seam spike. If the ADR ages past the review date still Proposed, either accept, reject, or kill the draft — do not let it accumulate as fake coverage.
Open-ended Proposed ADRs become a museum of unfinished arguments. That is a different failure from a decision log that stays Accepted forever after the system moved; both leave the team unsure what binds the build. One never closed. The other never revisited.
In practice we keep Proposed ADRs out of the "current constraints" list used in scoping and steering. Steering reads Accepted only. Proposed lives in a short queue with owners and due dates, same discipline as open discovery questions.
Accept needs an owner and a revisit trigger
Acceptance without an owner is how ADRs become wallpaper. Someone has to be accountable when the trade-off bites — latency on a webhook ingest, a Sanity schema that cannot support the campaign surface, a widget process that must not write. Write the owner on the same line as Accepted.
Acceptance without a revisit trigger is how Accepted turns into a museum entry. Name what would force a new ADR: a new integration, a measured SLO miss, a compliance constraint, a superseded alternative becoming viable. Status hygiene is not bureaucracy; it is how the corpus stays trustworthy when people rotate.
This pairs with leaving discovery with decisions, not a backlog. An Accepted ADR is one form of those decisions. A Proposed ADR is still an open question wearing formal clothes.
Where the ADR has to live to matter
If the only copy of a decision is in a slide deck from last quarter's advisory call, it will not survive contact with a pull request. Keep Accepted ADRs next to the code they constrain — in the repo the builders actually open — and require a link from significant PRs when a seam choice is in play.
Slack threads and standing calls are fine for forming the argument. They are not the record. We already treat chat as a poor decision archive; a Proposed ADR that never graduates is the same archive with better formatting.
When AI agents start reading the ADR corpus for context, Proposed-as-Accepted becomes actively dangerous. The agent will treat draft language as policy. Status is not metadata you can ignore because the prose sounded decisive.
What we check in a consulting review
Open the ADR directory and count Proposed older than the review window. Those are unfinished decisions, not architecture coverage. For each Accepted entry, confirm an owner and at least one revisit trigger. For each significant recent PR that crossed a seam, confirm it linked an Accepted ADR or opened a new Proposed one the same day.
If the team has templates and no Accepted records, stop adding templates. Close three live choices — store ownership, auth boundary, integration idempotency — before drafting the next empty file. Volume is not governance.
The milestone is a short list of Accepted constraints the build can be held to. Until Status moves, the ADR is research. Treat it that way, and the calendar stops pretending the architecture was already decided.
Questions
- When should Status leave Proposed?
- When a named review accepts or rejects the choice, with an owner and a revisit trigger written down. If you cannot name those, keep it Proposed and keep it out of the current-constraints list.
- How is this different from a Slack decision?
- Slack settles a moment and decays. An Accepted ADR is the durable record. A Proposed ADR is closer to an unfinished thread — useful draft, not yet binding.
- Do small choices need an ADR?
- No. Reserve ADRs for choices that constrain multiple surfaces or are expensive to reverse. Over-filing Proposed stubs is how the corpus loses signal.
Sources
- Architecture Decision Records Guide 2026 — status lifecycle — Proposed → Accepted → Deprecated / Superseded; ADRs next to code; PR enforcement.
- ADRs as governance, not passive docs — Debt-aware ADR practice; structured review instead of open-ended discussion.
- Related: A decision log is not a museum
- Related: A Slack thread is not a decision record