How to deal with conflicting ADRs? AI picks what suits it best.

[CodeMarr]

Hi Matt — question about ADRs in domain-modeling.

The classic rule is that an ADR is a timestamp: you never change it, and if the decision changes you write a new one. ADR-FORMAT.md doesn't say that. The only hint is one optional line — Status frontmatter, superseded by ADR-NNNN, "useful when decisions are revisited".

The problem I keep hitting: once you have a few dozen ADRs, an early one and a much later one say opposite things — A here, B there, true here, false there. Both files still read as "accepted". An agent greps the ADR folder, opens a hit, reads the first few lines and stops. If the supersede note is buried in the body, it never sees it. So it now has two conflicting decisions and no rule for which one wins — and it just picks whichever one suits the change it already wants to make. It never asks; it justifies.

Two questions:

1. Did you intend ADRs to be immutable, or did you leave that open on purpose?
2. Would you make the status line mandatory and at the top of the file? For humans it's fine as optional. For agents it's the only part that reliably gets read.

[hamedrabah]

For agents, I would make status mandatory rather than relying on prose inside the ADR. Keep ADRs immutable except for their status metadata, and resolve a conflict by creating a new ADR that explicitly supersedes the old one.

A workable header is:

status: accepted # proposed | accepted | superseded | rejected
superseded-by: ADR-0042

Then add an ADR index and tell agents to use only accepted ADRs. A small CI check can reject missing statuses, duplicate IDs, and a superseded ADR without a valid target.

The current ADR format makes status optional, including superseded by ADR-NNNN. That is readable for humans, but too ambiguous for an agent choosing among contradictory files. Mandatory machine-readable status plus a superseding link removes that choice.

[707io]

Hi Matt — question about ADRs in domain modeling.

The classic ADR rule is that an ADR is immutable: if a decision changes, you write a new ADR rather than editing the old one. ADR-FORMAT.md doesn’t explicitly say that; it only has an optional Status field, such as “superseded by ADR-NNNN.”

The issue I’m running into is that after a few dozen ADRs, older and newer decisions can directly conflict while both still appear “accepted.” An agent may grep the folder, find an older ADR, read the beginning, and never notice that it was superseded. It then has conflicting guidance and may simply choose whichever supports the change it already wants to make.

So two questions:

1. Did you intend ADRs to be immutable, or intentionally leave that open?
2. Would you consider making the Status field mandatory and placing it near the top of the file? For humans optional is probably fine, but for agents it seems like the one piece of metadata they’re most likely to reliably see.

[vinkay215]

I think there are two separate questions here: what the current format guarantees, and what convention would be safest for agents.

From the current ADR-FORMAT.md, I don't think we can confidently say ADRs are intended to be immutable. Status is explicitly optional, including superseded by ADR-NNNN, so the format currently leaves that policy somewhat open.

For agent-driven repos, though, I think the safer convention would be:

1. Treat accepted ADRs as immutable historical records.
2. When a decision changes, create a new ADR instead of rewriting the old one.
3. Mark the old ADR as superseded.
4. Put that status at the very top of the file, where an agent cannot miss it.

For example:

---
status: superseded
superseded_by: ADR-0042
---

# Use PostgreSQL for event storage

...

And the replacement:

---
status: accepted
supersedes: ADR-0017
---

# Use DynamoDB for event storage

...

The important part for agents is that conflict resolution needs to be deterministic.

If an agent finds two contradictory ADRs and both appear accepted, it should not choose whichever supports its current implementation. It should stop and surface the contradiction.

Something like:

If ADRs conflict:
1. Prefer an explicitly accepted ADR over deprecated/superseded ADRs.
2. Follow `superseded_by` / `supersedes` links.
3. If both remain accepted, do not infer which one wins — ask.

So yes, I think making status metadata prominent and mandatory once an ADR is superseded would substantially reduce this failure mode.

I wouldn't necessarily require status metadata on every brand-new ADR if the goal is to keep ADRs lightweight, but as soon as a decision is revisited, the relationship between the old and new ADR should become explicit and machine-readable.