What were we thinking?
Gavel logs and the memory of why
You’ve sat in the meeting, or opened up the code. You’ve looked at the documentation. You’ve found yourself thinking “why did they do that?” It’s even worse when you’re looking at something you participated in from five years ago. “What were we thinking?” You might half-remember a conversation, or one of your colleagues can hazard a guess because of something else that was happening at the time. You were too busy to fully document. The decision still lives. The why is gone.
A few years ago, an engineer I worked with introduced the ‘gavel log’ to the team. We were recording the moment a gavel came down on a decision. But the point wasn’t to record the decision. That’s self-documenting. The point was to make a record of what we were choosing between, why this option, what we expected. The log lived in a shared document. We could go back to it.
The first time we revisited a decision, the original conversation was a year old. One person had moved teams. Two others had left the company. The log told us what we’d known at the time, what we’d thought about, the alternatives we’d considered. This helped us ground ourselves in our past selves. We could see how the world had shifted; the decision needed to be revisited. Now we knew what we’d been thinking when we’d made it.
What the log actually held
Gavel logs aren’t useful because they record decisions. They’re time capsules. They record the trade-offs, the alternatives we’d rejected and our reasoning. Our hypothesis about how this would play out. The customer request we’d weighed against the engineering effort.
Decisions are made under specific conditions. Six months later, none of those things look the same. Six months later, the team can barely recall the environment that pushed them one way or another. Questioning if the decision still holds isn’t questioning if it was right at the time. The gavel log helps you remember what you thought was right at the time.
The false friends
This goes further than meeting minutes, which record attendance and actions, and sometimes a decision. They rarely record the trade-offs that produced the decision, because trade-offs are messy and minutes tend to summarise, to be politically safe. AI summaries of meetings do the same thing, faster and more politely. They flatten the conversation that produced it.
ADRs come close. Good ADRs name the choice and the alternatives considered. But ADRs often skip the recommendation that kickstarted the debate, the assumptions baked into the decision, and the conditions that would invalidate it. ADRs only apply to a subset of the decisions a team makes, they don’t capture every debate.
Not every decision
The same is true of gavel logs. Most decisions don’t need an entry. Many smaller decisions can be made and everyone can move on. The ones that earn an entry are the ones with perceived consequence. The strategic bet that the next phase of the product will depend on. The team-shape decision that defines how work flows. The customer trade-off that determines what gets built. Anything where, a year from now, the question “why did we do that?” is likely to land in someone’s lap. If it requires more than a comment in your code, if there’s genuine debate about alternatives, then it’s worth creating a gavel log.
What the record needs to record
A useful gavel log captures what was true at the time: the customer evidence, the team configuration, the technology constraints, the competitive position. It captures the alternatives that were on the table and the reasons each was set down. It names the recommendation and the reasoning behind it. It states what you expected to happen, in language specific enough that you’d know if you were wrong. And it names the conditions that would prompt you to revisit; the things that, if they changed, would make the decision worth reopening. Each entry is written for the reader who’ll inherit it, not for the team that’s in the room.
Keeping the practice alive
Any team that’s had to wonder about some legacy code it’s unpicking can be motivated to start a gavel log. It’s a way to protect their future selves from being in the same position. But, just like a summer fitness routine that doesn’t survive a rainy autumn day, it can be easy to let things go if the commitment isn’t there. Many teams who attempt this have only created a graveyard of three-month-old entries. The fix isn’t heroic discipline. It’s a decision about who owns the log and when it gets updated. This in itself can be a record on the gavel log.
What survives the room
When the practice sticks, decisions stop happening behind closed doors, and become artefacts that live in the open. New colleagues see the reasoning behind the structures they’ve inherited. People who haven’t been in the room can comment without re-litigating the conversation. The clarity of who decides what becomes a touchstone for how to think about the team’s choices.
The team that started the gavel log eventually disbanded. A while later, I left the company. Years later, I met a former colleague for a drink. We were reminiscing about the times we’d spent together, and he mentioned the company had just started refactoring a system we’d built. “I opened up the code,” he said, “and our fingerprints were all over it.” There were references in comments to decisions that had been made, and the gavel logs to support them. Nobody in the modernisation project had to wonder why we’d taken a particular approach. The logs told them.
The decision log doesn’t make better decisions. It keeps the reasons available, so the organisation can think about its own thinking when the world changes.