A Decision Log Template for Engineering Teams (And Why It Goes Stale)

A decision log is a running list of the decisions a team has made, one row per decision, with what was decided, who decided it, why, and when. The template below gives you the fields to copy, a filled-in example, and the two habits that stop the log from going stale.

A log is the simplest form of a system of record for decisions. It will not hold the full argument behind a big decision. It does hold the result in a place where anyone can find it, which is what most teams are missing.

The decision log template

Copy this into a spreadsheet, a Notion database or a Markdown file in your repo. Each row is one decision.

Field	What to write
ID	A short number so other docs can link to it, such as D-042
Date	The day the decision was made, not the day it was logged
Decision	The result in one sentence, written as a fact
Owner	The one person who made the call
Consulted	Who gave input, and anyone who disagreed
Why	The main reason this option won
Options rejected	What else was considered, and why each lost
Reversible?	Easy, costly, or no
Authority	Whose remit the decision falls under
Review date	When the team should look at it again
Links	The thread, ticket, pull request or RFC behind it
Status	Active, or replaced by a later decision (give its ID)

A filled-in example entry

Field	Example
ID	D-042
Date	2026-09-30
Decision	New services publish events to the shared queue instead of calling each other directly
Owner	Dana Kim, platform lead
Consulted	Payments and search teams. Search disagreed and asked for an exception for reads
Why	Direct calls created a chain of outages during the last two incidents
Options rejected	Keep direct calls with retries: hides the problem. A service mesh: too much to run for a team this size
Reversible?	Costly
Authority	Platform architecture
Review date	2027-03-31
Links	RFC-17, PLAT-883, incident review from September
Status	Active

A reader who missed every meeting can now answer the questions that usually cost an hour: what we chose, who chose it, what we turned down, and whether they are allowed to change it.

The three fields most templates miss

Most decision log templates stop at date, decision, owner and reason. Those four tell you what happened. The next three are the ones that save time later.

Start with options rejected. Without it, someone will propose the losing option again in six months, and the team will spend a meeting finding out why it lost. One line per rejected option is enough.

Authority tells the next reader whether the decision is theirs to change. A decision with a named authority is settled until that person or group reopens it. A decision with no authority listed is an open invitation to argue.

The review date turns the log from an archive into a schedule. Some decisions are made for a season: a vendor for this year, a process for this quarter. A review date makes sure someone looks again on purpose, rather than by accident during an outage.

Why a decision log goes stale

Almost every team that starts a decision log has stopped updating it within a few months. The causes are the same everywhere.

Nobody owns it. If the log belongs to everyone, entries depend on whoever remembers. Give it one owner, often a tech lead or engineering manager, whose job each week is to check that last week's decisions are in it.

Writing an entry takes too long. If a row needs ten minutes and three links, people skip it. The template above takes two or three minutes when filled in on the day. Filled in a month later, it takes much longer, because nobody remembers the details.

Nobody reads it. A log that nobody consults gets no new entries, because nobody notices the gaps. The fix is to point people at it: link the log in planning docs, ask "is it in the log?" when a settled question comes back, and answer new hires' "why did we do this?" with a link to the row.

Old rows get edited. When a decision changes, add a new row and mark the old one as replaced by the new ID. If people edit history, the log can no longer tell you what was true at the time.

Signs your team needs a decision log

You probably need one if any of these sound familiar:

• The same question comes back at planning every quarter.
• New engineers ask why the system works a certain way, and only one person can answer.
• Two people made opposite calls on the same issue in the same week.
• A decision from a Slack thread was reversed and half the team never heard.
• Post-incident reviews keep ending with "we didn't know that had been decided."

If decisions keep getting reopened even with a log, the problem may be ownership rather than record keeping. See why teams keep re-arguing decisions, and pair the log with a decision authority map that says who owns which kind of call.

Ask the log questions instead of only storing it

A log earns its keep when people use it to answer questions. Three questions come up most: what did we decide about this, who decided it, and is it still current? If your log is a spreadsheet, filtering by owner, status and links gets you most of the way. If it lives in your repo, plain text search works well.

The quarterly review is the other use. Once a quarter, the owner filters for rows whose review date has passed, and the team spends twenty minutes on each: keep it, change it (with a new row), or retire it. That keeps the log a list of decisions that are true now, not only a history.

Logs, records and ADRs

A log is one row per decision. For the large decisions, the row can point to a longer document. In engineering that document is often an ADR; see architecture decision records. For business decisions such as pricing or hiring, the same idea is a team decision record. The log is the index, and the records hold the detail.

Where the log lives matters less than whether people use it. If your team already works in Notion or Confluence, start there; see the notes on Notion as a decision log and Confluence as a decision record. Leadership teams keep a slightly different version, covered in the executive decision log.

Where StandIn fits

StandIn answers your teammates' questions from the work you have already done, in your words, with a source under every answer. When a decision is in the log or in your brief, someone can ask about it while you are away and get the answer with your name and the source. When it is not written down, StandIn never guesses: it says so and points to the person who knows. See how StandIn works.