Why did we decide this? How to stop re-litigating old decisions

"Didn't we already try that?" Somebody remembers that the team evaluated Kafka, or moved off MongoDB, or added that strange retry loop for a reason. Nobody remembers the reason. So the debate starts again from scratch, or worse, the change goes in, breaks something, and gets reverted a month later.

Re-litigating decisions is not a sign of a bad team. It is what happens when the outcome of a decision survives but the reasoning doesn't. This post covers how to keep the reasoning attached.

What re-litigating actually costs

Some of the cost shows up in commit history. Shimagaki and colleagues studied why commits get reverted across open-source and proprietary projects. Between 1% and 5% of commits were reverted, and in the proprietary projects at Sony Mobile, reverted commits stayed in the code for 24 to 35 days before being backed out. Reasons involving external parties, such as changed requirements, dominated, and the authors concluded that many reverts could have been avoided with better team communication and change awareness.

Awareness is a known weak spot. In Microsoft's study Software Development at Microsoft Observed, 61% of developers said they struggle to stay aware of changes elsewhere that affect their own code.

Most of the cost never shows up in a commit at all: the hour-long meeting revisiting a choice made two years ago, the senior engineer who re-explains it for the fourth time, the new lead who quietly rebuilds something the team already rejected.

Chesterton's fence, applied to code

The old principle goes like this: if you find a fence across a road and don't know why it's there, don't tear it down until you find out. In software the fence is the odd retry, the duplicate table, the hard-coded timeout. As one essay on puts it, deleting code is cheap but learning why it exists is expensive.