Decision logs that stop repeat architecture arguments

Why the same argument keeps coming back

Teams do not repeat architecture debates because people are careless. They repeat them because people remember the headline and forget the conditions.

Everyone remembers that the team chose PostgreSQL over a document database, or kept a monolith instead of splitting services. Fewer people remember why. Maybe the team had two engineers, four weeks to ship, almost no budget, or a recent outage that pushed everyone toward the safest option.

That missing context changes everything. Six months later, someone asks, "Why are we still doing it this way?" One person remembers speed. Another remembers cost. Someone else remembers a scaling concern that may not even matter anymore. Once the reason gets fuzzy, the old argument starts again.

Team changes make this worse. New engineers, product managers, and founders inherit the current system without seeing the tradeoffs that shaped it. If nobody wrote those down, the choice can look random, outdated, or political.

Time also changes the facts. Traffic grows. Budgets shrink. Vendors raise prices. Tools improve. Painful workarounds become normal, so people stop questioning them. Then the same issue comes back, not because the team ignored the earlier decision, but because the world around that decision changed.

Chat tools add another layer of confusion. Part of the reasoning lives in Slack. One objection sits in a ticket comment. A benchmark is buried in a doc nobody opens. The final call happened in a meeting, and the notes say only "agreed." When the story is split across five places, nobody has the full picture. People rebuild it from fragments.

That is why decision logs help more than most teams expect. They do not stop disagreement. They stop amnesia. Instead of arguing from memory, teams can look at what they knew, what they feared, what they accepted, and whether those conditions still hold. The conversation gets calmer fast. It becomes less about who remembers best and more about whether the old choice still fits.

What a decision log should do

A decision log is not a diary of meetings. It is a short record of one meaningful choice.

If the team changes a database, picks a queue, splits a service, or decides to leave the current setup alone for now, that choice gets its own entry. One entry per choice keeps the record clear. When teams pack three decisions into one note, nobody can tell what they actually agreed on.

A useful log answers five questions without forcing anyone to dig through old chats:

• What problem were we trying to solve?
• What real options did we consider?
• What did we choose?
• Why did this choice make sense then?
• When should we review it again?

That last question matters more than it looks. A choice can be right for the current stage and wrong later. Maybe traffic is still low, the team is small, or speed matters more than flexibility. Write that down plainly. "We chose the simpler path because two engineers need to ship in four weeks" is much better than "selected for simplicity."

A review date or clear trigger keeps the note honest. The trigger can be a number or an event: monthly active users reach 50,000, error rates rise, enterprise customers ask for audit trails, or the team hires another backend engineer. That gives people a reason to revisit the decision with facts instead of vague frustration.

A good entry is short enough to write in ten minutes and specific enough to survive turnover. A new engineer, founder, or outside advisor should be able to read it once and understand the tradeoff. That is the job. The point is not to prove the team was right forever. The point is to show why the choice made sense at the time.

What to record in each entry

Most arguments restart because the old choice lives in code, not in writing. A good entry gives just enough detail for a new person to see what happened, what limits shaped it, and when it deserves another look.

Keep each entry short. If it takes half an hour to read, people will skip it and go back to arguing from memory.

Most entries need six parts:

1. The decision in one clear sentence. Start with "We will..." so nobody has to guess what the team chose.
2. The owner and the date. Name the person responsible and record when the team made the call.
3. The constraints. Write down the limits that mattered, such as a four-week deadline, a fixed budget, one backend engineer, or a vendor contract.
4. The tradeoffs. Say what the team accepted on purpose, like faster delivery now in exchange for more cleanup later.
5. The rejected options. Name the main path the team did not take and why it lost.
6. The review date or trigger. Pick a date, traffic threshold, budget change, team growth point, or incident type that should reopen the discussion.

The decision sentence matters a lot. "Use PostgreSQL for all product data until launch" is clear. "Keep the data layer simple" is not. One tells people what to do. The other invites another debate.

The constraints section is where honesty matters most. Teams often write as if they picked the best design in a vacuum, when they really picked the best design they could afford that month. That is normal. Just say it.

A product team might write: "We will keep one API service until we reach 50,000 daily active users." The note would name the engineering lead, record the date, explain that the team has two developers and eight weeks to launch, note the tradeoff between speed and service isolation, say they chose not to split into microservices yet, and add a review trigger tied to traffic or incident volume.

That takes about ten minutes to write. It can save weeks of repeated debate later.

How to write one in 10 minutes

Most teams overcomplicate this and end up writing nothing. A good entry is plain, short, and tied to a real choice the team has to make now.

Set a 10-minute timer. If the team cannot explain the decision in that time, the problem is usually still fuzzy.

1. Write the decision in one sentence. Use direct language like "Use PostgreSQL for event storage" or "Keep the monolith for the next six months."
2. Add the problem in two or three lines. Say what hurts, what changed, or what deadline is forcing the call.
3. List two to four real options. One option can be "do nothing for now" if that is honestly on the table.
4. Pick one option and write the tradeoffs. Be blunt about what you gain, what you give up, and who feels the downside first.
5. Add a review date or trigger before you close the note.

That is enough for most architecture decisions. You do not need an essay, a diagram, or a meeting transcript.

If a team spent three weeks arguing about queues, the final note can still fit on half a page: current load is low, one service owns the work, retries are simple, so a database table wins for now. Review the choice after the next major customer launch.

Store decision logs where the team already works every day. That might be the repo, the wiki, or the same place you keep runbooks. If people need to remember a special tool, they will stop using it.

One small habit helps a lot: end each entry with the name of the person who made the call and the people who joined the discussion. Months later, the team has a starting point if it needs more context.

A simple example from a product team

A startup is building search for its first few thousand users. The product is still young, the catalog is modest, and the budget is tight. Search matters, but it is not the only thing on the roadmap.

One group wants to keep search inside PostgreSQL for now. The argument is simple: the data already lives there, setup is fast, and the team can ship this week. Another group wants a separate search service because they expect better ranking, more filters, and fewer limits later.

Without a decision log, this argument tends to come back every few weeks. With one, the team writes down the facts it has today.

The note can be very simple. The current need is basic search across product names and descriptions. Expected load is around 300 to 500 searches a day for the next few months. The team has no extra infrastructure budget this quarter and no engineer available to run another service. The real options are PostgreSQL search now or a separate search service now.

The team chooses PostgreSQL search. It is not perfect. Relevance may be weaker, and advanced search features will take more work. But it matches the current size of the product and keeps operations simple.

The log should also say why the team rejected the separate service. It would add one more system to deploy, monitor, back up, and debug. For a small product, that cost is often bigger than the search gain.

The review trigger is the most useful part. Instead of saying "we will revisit this someday," the team sets a threshold: review the decision when search volume stays above 5,000 queries a day for two straight weeks, or when the catalog passes 100,000 items. If neither happens, the simpler setup stays in place.

Months later, nobody has to guess why the team made the call. They can read the context, the tradeoffs, and the expiry point. What could have turned into another long debate becomes a quick check against facts.

How to use review dates without creating busywork

Most architecture choices do not need a monthly reminder. They need a simple rule that tells the team when to look again.

That rule can be a date or a trigger. A date works well for decisions made under uncertainty, like picking a vendor, cache, or queue during an early release. A trigger works better when the choice depends on conditions that might change quickly.

Good triggers are easy to notice in daily work. They usually connect to numbers the team already watches, such as traffic crossing a set level, latency staying above a limit for two weeks, monthly cost going over budget, or team growth reaching the point where the current setup slows people down.

This keeps decision logs practical. You are not asking people to reopen old arguments on a schedule just because a date arrived. You are asking them to check the decision when reality changes.

Start each review with one question: do the original assumptions still match what the team sees now?

Maybe the team chose a simple deployment setup because one engineer handled releases. Six months later, five engineers deploy every day. The old choice may still work, but the reason behind it is gone.

When that happens, do not rewrite history. Keep the old entry. Add a new one beside it with the new context, new tradeoffs, and the new date. That gives the team a clean trail. People can see why the first call made sense then and why the second call replaced it.

You can also skip a review. That should feel normal, not like failure. If the trigger did not fire, or the team checked and nothing important changed, add a short note and move on. One sentence is enough: traffic is still below the threshold, costs are stable, no action needed.

That is the point of expiry dates. They stop stale decisions from living forever. They should not create another meeting nobody wanted.

Mistakes that make logs useless

A log stops helping when it takes more effort to read than it took to make the decision. If one entry turns into a long essay, people will skip it and ask a teammate instead. That defeats the point.

Another common mistake is saving only the final choice. "We picked service A" is not enough. People need the pressure around the decision too: what problem pushed the team to act, what limits mattered, and what tradeoffs the team accepted. Without that context, the same debate comes back a few months later because nobody remembers why the choice made sense.

Teams also weaken their own logs when they leave out rejected options. This sounds minor, but it matters. If the note never says the team considered two other paths, later readers assume nobody looked at them. Then someone brings up an old option as if it were new. One short line per rejected option is usually enough.

Review ownership is another quiet failure point. A review date without a name beside it is decoration. Someone has to check whether the old constraints still apply.

Storage can ruin a good habit too. If logs live in a folder or tool the team rarely opens, they might as well not exist. Keep them close to the work.

A useful entry lets a new teammate answer a few basic questions fast: What did we choose? Why did we choose it then? What else did we consider? Who reviews it later? Where can I find the note without digging?

If a note cannot answer those, it is probably just a record that something happened. It is not a decision log the team can use when the argument comes back.

A quick check before you mark it done

A good entry should make sense to someone who missed the meeting. If a new engineer, product manager, or founder can read it in two minutes and explain the problem back to you, the note is clear enough. If not, add one or two plain sentences about what forced the decision now.

Then check whether the entry shows the road not taken. Teams often write the final choice and skip the rejected options. That gap is one of the main reasons old architecture arguments return.

Read the tradeoffs out loud. If the wording sounds stiff, rewrite it. "Cheaper to run, slower for large reports, easier to support" works better than polished jargon because people can test the logic instead of guessing what you meant.

A quick final pass catches most weak entries:

• The problem is clear near the top.
• The chosen option and rejected options are named.
• The tradeoffs use everyday language.
• The note has a review date or a clear trigger.
• The title and storage location make it easy to find later.

Findability is the check people skip most often. If the entry sits in a random folder with a vague title like "API notes," nobody will use it. A clear name like "Use PostgreSQL for billing events, review in Q4" gives people a real chance of finding it when they need it.

If one of these checks fails, fix it before you close the task. Most gaps take five minutes to clean up. That small effort can save hours of repeated debate later.

What to do next with your team

Pick one home for every new entry and keep using it. A docs page, repo folder, or shared workspace can all work. The tool matters less than one rule: if a choice affects architecture, cost, security, or delivery speed, record it in that same place.

Do not start by trying to reconstruct old history. That usually turns into cleanup work nobody wants. Start with the next real debate that is already open: whether to split a service, buy a tool, replace a queue, or keep something in-house.

Ask one person to write the first draft right after the discussion. If everyone owns it, nobody does. The draft does not need polish. It just needs enough context that someone can read it three months later and understand why the team made the call.

Keep the format short: decision, context, options considered, why this choice won, and review date. That is enough for most teams. If an entry takes half an hour, people will avoid it. If it takes 10 minutes, the habit usually sticks.

Then set one review each quarter. Do not reopen everything. Look at decisions with a review date coming up, plus any choice that is now causing obvious pain. A short meeting is often enough because the team is checking facts, not replaying old opinions.

This is when decision logs start paying off. Instead of hearing, "I thought we already decided this," you can see what changed: traffic grew, hiring changed, costs went up, or a tool did not work the way the team expected.

Small teams get the most out of this when they keep it boring and regular. One place, one short format, one quarterly review. That is usually enough to stop the same architecture discussion from turning into the same fight every quarter.

If your team keeps getting stuck in repeated architecture arguments, Oleg Sotnikov at oleg.is helps startups put simple decision records and review habits in place as part of his fractional CTO advisory work. Sometimes a little outside structure is enough to make the habit stick.