Reversibility
Rate each decision by how expensive it is to reverse, and spend effort proportional to that cost.
Why
Some decisions are cheap to reverse (which cache library — swap in a day) and some are not (which database — migrate in 6 months). Spending the same effort on both is wasteful: a 2-week decision process for a 1-day-reversible choice is paralysis; a 1-day process for a 6-month-reversible choice is recklessness. Reversibility rating (cheap, moderate, expensive) calibrates the process: cheap decisions get a PR + a comment, moderate get an ADR, expensive get an ADR + prototype + principal sign-off. This is the 'one-way vs two-way doors' principle — most decisions are two-way, and treating them as one-way is the main source of organizational paralysis.
When
Rate every decision at proposal time. Takes 5 minutes. Re-rate if the cost estimate changes.
How
1. For the proposed decision, estimate the cost to reverse: - Cheap (< 1 eng-day): swap a library, rename an internal API, change a config - Moderate (1 eng-week to 1 eng-month): change a framework, swap a managed service - Expensive (> 1 eng-month): change a database, change a cloud provider, re-architect 2. Apply the matching process: - Cheap → PR with a comment explaining the choice; no ADR - Moderate → ADR with alternatives; tech-lead approval - Expensive → ADR + prototype + principal/architect sign-off + migration plan 3. Document the reversibility rating in the ADR (if one is written) 4. If a cheap decision turns out to be expensive to reverse, stop and re-rate
Example
Decisions and reversibility:
- Switch linter to Biome → CHEAP (1 day to swap back) → PR + comment, no ADR
- Adopt tRPC instead of REST → MODERATE (2 weeks to swap back) → ADR-019
- Move from Postgres to DynamoDB → EXPENSIVE (6 months to migrate back) →
ADR-020 + prototype + principal sign-off + 3-month migration plan
- Rename /api/v1/users to /api/v1/accounts → MODERATE (consumer migration) → ADR-021
The expensive decision gets 10x the process of the cheap one — proportional effort.Common Problems
- ⚠Treating every decision as expensive — the team writes ADRs for linter configs and the real decisions get lost in the noise; rate honestly.
Best Practices
- ✓Default to 'cheap' unless you can articulate the specific cost of reversing — most decisions are reversible, and assuming they're not is paralysis.
- ✓Re-rate reversibility when you learn more — a decision that looked cheap (swap a library) may be expensive (the library is now in 50 files); update the process.