You want to reverse a decision recorded in an ADR two years ago, and everyone who made it has left. How do you go about it?
6 min readUpdated 2026-08-15Target archetype: Big Tech, Enterprise Captive, Product Startup
0
Answer
Short answer
Reconstruct the original context first and test whether it has genuinely changed or whether you simply inherited a cost you dislike, then write a new record that supersedes rather than edits the old one, price the half-reversed state explicitly, and get agreement from the teams who now carry the consequences.
An ADR reversal should produce a supersession trail, not an edit that erases history. Good ADR practice leaves the old ADR intact, records why the context changed, and writes the new ADR with an explicit supersession link. Weak supersession hides the previous decision and forces future reviewers to rediscover the argument. Strong ADR supersession makes the change auditable without pretending the original authors were wrong.
Was this answer helpful?
Likely follow-ups
→The original ADR records a consequence you are now suffering, listed as knowingly accepted. Does that make reversal harder or easier to argue?
→How do you handle a decision whose context you cannot reconstruct at all because nothing was written down?
→What do you do when half the estate has migrated to the new decision and funding stops?
→How would you write today's reversal so that whoever reverses it in two years has what you did not?
The instinct on finding an inconvenient old decision is to argue against its conclusion. The useful move is to read it for its constraints, because the conclusion was a function of those constraints and you are only entitled to a different conclusion if they have changed. A well-written record makes this easy: it says what was true at the time, what options were considered, and which consequences were knowingly accepted. A badly written one gives you only the choice, in which case reconstructing the context is the first piece of work and you should say so rather than skipping it.
The specific thing to look for is whether the pain you are feeling appears in the original consequences section. This is the fork in the whole conversation. If the record says "we accept that this couples deployment of the two services" and your complaint is that deployment is coupled, then nothing has changed and you are proposing to spend money to undo a trade-off the organisation made deliberately. That argument can still be won, but it has to be won on the grounds that the price is now higher than anticipated, with evidence of how much higher, and that is a much more disciplined case than "this was a mistake".
If the pain is not in the record, you have found either a consequence nobody foresaw or a change in the world, and both are legitimate grounds. Say which. An unforeseen consequence is an argument about the original analysis; a changed world is an argument about the present, and only the second one lets you avoid implying the previous team was careless, which matters more than it sounds when their colleagues are still in the room.
The four things that make reversal legitimate
Four categories of change actually justify revisiting, and naming which one applies keeps the discussion out of taste.
The constraint has gone: the managed service that did not exist now does, the licence that prevented an approach has lapsed, the team of three is now a team of thirty. The scale assumption was wrong: the decision was correct for the volume expected and the volume is an order of magnitude different, in either direction. The cost turned out to be materially higher than the record predicted, and you can show that with something measured — incident count, change lead time, spend, the number of people who have to be involved in a routine change. Or the decision was made for an option that has since been withdrawn from under you, which is really the vendor and dependency case wearing a different hat.
What does not appear on that list is that a new team dislikes the technology, that the industry has moved on, or that someone has arrived with experience of a different tool. Those are the reasons reversals most often get proposed and are the reasons they most often fail review, because none of them answer the question of what the organisation gets for the money.
Supersede, never edit
The mechanical part is simple and candidates get it wrong often enough that it is worth stating precisely. The old record stays exactly as it is. You write a new one, it references the old, and the old one gets a status marking it superseded and a pointer forwards. You do not edit the original's decision, you do not delete it, and you do not update its context to reflect what you now know.
The reason is that the log is the only mechanism by which anyone can reconstruct why the system is shaped as it is. An edited record silently destroys the explanation for every line of code written between the two decisions, and the person who suffers is the engineer in two years who finds code that matches neither the current record nor any record at all. Keeping both means the estate is legible: some of it was built under decision one, some under decision two, and the dates tell you which.
The new record also has an obligation the original did not. It has to state what happens to everything already built the old way, because that is now scope. A supersession that says only "we will use B from now on" has created two architectures and called it a decision.
The half-reversed state is the real risk
Assume the migration will stall, because migrations stall when priorities move, and design the decision so that stalling is survivable. That means being explicit about the state you will be in when only part of the estate has moved, and answering three questions in the record itself: which systems are expected to remain on the old decision indefinitely and whether that is acceptable, what the cost of running both is per month or per quarter, and what the minimum coherent stopping point is if funding disappears halfway.
Loading diagram…
The branch to look at is the lower one, because it is the common outcome and the one nobody plans for. An organisation carrying three unfinished reversals is in a worse position than one that never started any of them, and the cost is not just infrastructure: every new engineer has to learn both ways, every change has to be made twice, and every review starts with an argument about which side of the split this component sits on. If you cannot fund the reversal to completion, the more honest decision is to accept the original and write down that you have accepted it.
Who agrees, when the authors have gone
Authority over a decision does not transfer to whoever finds the document. It sits with the people who now bear its consequences, which is usually more teams than made the original call, because two years of building has spread the dependency. Find them the way you would find callers of a legacy system: from observed usage rather than from an org chart, because the teams affected are the ones whose code depends on the shape the decision produced.
Then bring them a proposal with the reversal cost in it, not a critique of the original. The two failure patterns here are both social. One is reversal by fait accompli, where a team builds the new way and the record is written afterwards to legitimise it, which teaches everyone that records are theatre. The other is paralysis, where nobody feels entitled to change a decision whose authors have gone, and the organisation stays bound by constraints that expired eighteen months ago. The guard against both is a stated cadence: decisions with a material ongoing cost get a review date written into them, and arriving at that date is permission to reopen without anyone needing to accuse anybody of anything.
You are only entitled to a different conclusion if the constraints changed, so find out whether your pain is listed in the original consequences as knowingly accepted. If it is, argue about the price rather than the judgement — and either fund the reversal to completion or write down that you have chosen to live with the original.