Skip to main content

Reversibility: One-Way vs Two-Way Doors

What This Concept Is​

Some decisions can be undone cheaply; others cannot. Jeff Bezos labels them two-way doors and one-way doors:

  • Two-way door. If the decision is wrong, you can back out in days or a sprint, with bounded damage. Examples: which logging library, which internal metrics client, which style of validation.
  • One-way door. If the decision is wrong, you are stuck with it for quarters or years. Examples: choice of primary database, network protocol between services, public API shape, multi-region sharding strategy.

The two categories deserve different decision processes. Two-way doors should be decided quickly, with light review, and revisited if wrong. One-way doors deserve ATAM-style scrutiny, explicit alternative analysis, and written consequences.

Why It Matters Here​

Organizations fail in both directions. They over-review two-way doors and ship nothing ("six stakeholders weighed in on which HTTP client we should use"). They under-review one-way doors and live with them for a decade ("we picked GraphQL in a hackathon and it became the platform").

Reversibility is the decision process dial. Cluster 3 picks the right review method; this concept picks the right review weight. The ADR you write should state, in one line, which door you believe you are opening.

Concrete Example​

ADR-0012: Message serialization format

  • Status: Accepted
  • Context: We are about to freeze the wire format for events flowing through the event bus. Consumers include internal services, partner webhooks, and an offline analytics lake.
  • Door classification: One-way. Once partners consume v1 payloads, we cannot change serialization without a coordinated multi-quarter migration.
  • Decision: Protobuf with an evolution policy: only additive changes; field numbers never reused; required fields forbidden.
  • Consequences:
    • gain: compact payloads, strong typing, generated clients
    • give up: human-readable wire traffic; need a schema registry
    • tripwire: if analytics cannot handle Protobuf in its ingest, we discover this late

Compare to a sibling decision the same week: "use zap or slog for internal logging in the order service." Two-way door. No ADR, a short code-review discussion, commit.

Common Confusion / Misconception​

"If it goes into production, it's one-way." Wrong. You can ship a feature flag, measure for a week, and remove it. Shipping is not the same as locking in.

"One-way because switching costs time." Every change costs time. One-way means the cost is disproportionate to the decision - multiple quarters, migration code, stakeholder renegotiation, not just refactor time.

"Treat everything as one-way to be safe." This converts your team into a bottleneck. The cost of over-review is dead projects and slow learners. Calibrate instead.

How To Use It​

When capturing a decision:

  1. State the door classification in one line near the top. Make it a required field in your template.
  2. If one-way, enumerate at least two alternatives you considered and state why each was not chosen.
  3. If one-way, name the explicit conditions under which you would revisit the decision.
  4. If two-way, say so - and resist the review overhead the organization wants to attach to it.

Calibration note: the honest answer for mid-sized teams is that most decisions are two-way, but the painful ones concentrate in the one-way set. Protect time for one-way review; do not let two-way decisions consume it.

Check Yourself​

  1. For each: classify as one-way or two-way and say how you would confirm the classification. (a) public REST API shape for a partner program; (b) choice of cloud provider for a greenfield internal tool; (c) adopting OpenTelemetry for observability; (d) switching the internal build system.
  2. Name a decision your team treated as one-way that was actually two-way. What did over-caution cost?
  3. Name a decision your team treated as two-way that was actually one-way. What was the damage?

Mini Drill or Application​

Take your last 10 architectural decisions. Label each as one-way or two-way with one sentence of justification. Count:

  • how many one-way decisions had fewer than 2 alternatives written down
  • how many two-way decisions consumed more than 3 hours of meeting time
  • how many decisions you now think you misclassified

This is the core calibration exercise. Run it quarterly until the numbers stop surprising you.

Read This Only If Stuck​