On technical decisions that age well

Until this August, every repository on my forge merged pull requests by
squashing them. It was a style preference. Nobody would have called it an architectural
decision, and if you had asked whether it was reversible, the answer was
obviously yes: it is a dropdown.

Then a shared CI workflow was pinned by commit SHA from other repositories, the
way you are supposed to pin anything you depend on. The squash merge rewrote
that commit. The pinned SHA now existed only as a leftover pull-request ref,
the branch was auto-deleted, and the consumers had to be repinned. The same merge
diverged the GitHub mirror from the forge, which then needed a force-push to
reconcile. A dropdown had become a one-way door, and nobody had walked through
it on purpose.

The framework everyone quotes

Jeff Bezos split decisions into two types ^[1]. Type 1 decisions
are consequential and irreversible, one-way doors, and deserve slow, careful
deliberation. Type 2 decisions are reversible, two-way doors, and should be made
quickly by a small group with good judgement. His actual warning is the one
people skip: large organisations drift towards using the heavy process for
everything, and become slow.

I agree with all of it. The original version of this note said the same thing
in three paragraphs: treat reversible decisions cheaply, treat irreversible ones
seriously, and the mistake is treating them the same way.

What the framework assumes is that you can tell which door you are standing at.
At the scale of one team and one service, mostly you can. Across a few hundred
repositories, several clusters and two forges, mostly you cannot, because the
answer is not written on the door.

Reversibility lives in the dependents

A decision is reversible if you can undo it and everything that has come to
rely on it. The first half is a property of the decision. The second half is a
property of the system around it, and it grows after you decide.

The squash merge was reversible on the day it was chosen. It stopped being
reversible the day something pinned a commit hash, and nothing in the decision
itself changed on that day. That is the uncomfortable part: a two-way door can
lock from the other side while you are not looking.

I have seen three ways this happens often enough to name them.

1. Something pins it. Any identifier that another system stores becomes a
contract: commit SHAs, URLs, API field names, database IDs, message formats.
The moment a consumer records it, your freedom to change it depends on finding
and updating every consumer. If you cannot list them, treat the decision as
Type 1, whatever it looked like when you made it.

2. A name becomes load-bearing. One of my repositories was renamed a few
hours after its GitHub mirror was set up. The mirror kept working because
GitHub redirects the old name. Two weeks later the old name looked like a
duplicate project, and deleting it was approved as housekeeping. It was the
repository’s own mirror. The rename looked like a two-way door. In fact it had
quietly created a dependency on a redirect, and on the old name never being
reused. A rename is cheap to perform and expensive to finish.

3. The undo path decays. Before a cleanup run deleted nine local
repositories, it verified that preservation branches existed on both remotes. That was a perfectly good
undo path on the day it was checked. Ten weeks later one of the seven branches
had vanished from both. Nothing had lost it on purpose: branches are mutable,
and cleanup jobs, policy sweeps and housekeeping all prune them. The undo path
was a fact at one instant, and I had treated it as a permanent property.

In all three cases the decision was made correctly as a Type 2. In all three,
by the time it mattered, it was Type 1.

Buy reversibility before you need it

The useful move is not to slow every decision down. That is exactly the failure
Bezos describes. It is to make one-way doors two-way, cheaply, before walking
through them.

When I replaced squash merging with fast-forward-only merging across all 441
repositories, the change itself was the kind of thing that should make you
nervous: one script, every repository, no per-repo review. Two things made it
reasonable.

• Snapshot first. Before changing anything, I saved the existing merge
  settings for every repository. Rolling back became a single script against a
  known file, rather than an archaeology project.
• Keep the escape hatch that makes the new rule livable. Fast-forward-only
  merging becomes a trap once the main branch moves, because a stale pull
  request can no longer merge. Leaving rebase-update enabled meant every stale
  branch had a one-click way back to mergeable.

Neither step took long. Together they turned a fleet-wide, irreversible-looking
policy change into a two-way door, which meant it could be decided quickly and
by one person. That is the real dividend of reversibility: not safety for its
own sake, but permission to move fast.

Three questions before deciding

These are the questions I now ask before treating anything as Type 2.

1. Who will store this? List what will pin, cache, link to or parse the
   thing you are deciding. If the list is “nothing”, it is cheap. If you cannot
   produce the list, it is not.
2. What is my undo path made of, and will it still exist in three months?
   A branch, a redirect or a colleague’s memory is not an undo path. A tag, a
   snapshot file or an exported bundle might be.
3. Can I make it reversible for less than the cost of deliberating? Usually
   yes. A snapshot, a feature flag, a compatibility alias or a dual-write
   period is often an hour of work. It replaces a week of meetings.

What ages well

Decisions do not age. Their dependents do. A technical decision ages well when
whoever made it knew what would come to depend on it, kept the undo path
somewhere durable, and paid for reversibility while it was still cheap.

Most technical decisions are still bets. The difference between a bet and a
choice is still what you can undo. The part I would add after a few hundred
repositories is that what you can undo is not fixed when you decide. It is
whatever you have kept true since.