Decision Log Template for Engineering and Product Teams

Three weeks after a meeting, someone asks why the team picked Redis over in-memory rate limiting. Two people remember it differently. The person who made the call is on vacation. Someone goes looking for a Slack thread from March.

A decision log is a running record of the decisions a team has made: what was decided, why, what else was considered, who decided, and where it happened. Use one row per decision, link each row to its source, and mark old decisions “superseded” rather than deleting them. The template below works in a doc, a wiki, or a spreadsheet.

Teams usually start one after a few rounds of re-arguing the same question. The hard part isn’t the format. It’s keeping it current, because most decisions are made in places the log isn’t.

The decision log template

Copy this table into Confluence, Notion, Google Docs, or a README:

What goes in each column:

• ID: A short reference like D-014, so people can write “see D-014” in a ticket or PR.
• Date: When the decision was made, not when someone logged it.
• Decision: One sentence, written as the outcome. “Use Redis for all cross-instance rate limiting”, not “Discussed rate limiting.”
• Why: The reason in a sentence or two. This is the column people come back for.
• Options considered: What was ruled out. It stops the same alternative being proposed again in three months.
• Decided by: The person or group who made the call.
• Source: A link to the meeting notes, Slack thread, ticket, or doc where it happened.
• Status: Active, Superseded by D-0xx, or Reversed.

Spreadsheet version

For Excel or Google Sheets, paste this into the first cell and split it into columns (in Google Sheets: Data → Split text to columns):

ID,Date,Decision,Why,Options considered,Decided by,Source,Status,Revisit by
D-001,,,,,,,Active,

The extra Revisit by column is useful for decisions you made with a known expiry, like “ship without SSO until we have an enterprise customer.”

A filled-in decision log example

Here’s what a few weeks of entries look like for a platform team:

Notice D-012. It wasn’t deleted when the team changed its mind. It points to D-014, so anyone who finds the old approach in a ticket or old code can see it was replaced, and why.

How to keep a decision log people actually use

1. Log it the day it’s made. A decision logged a week later loses the “why”, which is the part people need.
2. Always link the source. “Decided in the Mar 19 postmortem” with a link can be checked. A row with no source becomes one person’s memory against another’s.
3. Supersede, don’t delete. When a decision changes, add a new row and mark the old one. The history is part of the value.
4. One owner per log. Not to write every entry, but to make sure entries get written. Without an owner, the log stops getting updated by week three.
5. Link decisions from where the work happens. Put “per D-016” in the ticket or the PR description. A log nobody links to is a log nobody reads.
6. Log decisions, not discussions. If nothing was decided, it doesn’t go in. Open questions belong in a separate list.

Decision log vs. decision register vs. ADR

These get mixed up, and you’ll see all three terms in project management guides.

Many engineering teams use both: ADRs for big architecture choices, and a decision log for everything else. Michael Nygard’s original post on documenting architecture decisions is still the best introduction to ADRs.

Why decision logs go stale

Look at the Source column in the example: a sprint planning meeting, a postmortem, a Slack thread, an eng leads meeting, another Slack thread. That’s normal. Decisions get made in conversations, and someone has to copy each one into the log afterwards. On a busy week, nobody does.

So the log drifts. It still exists and still looks official, but the decision from Tuesday’s thread isn’t in it. Now the log is worse than nothing, because people trust it. The ticket says CSV export, the log doesn’t mention dropping it, and someone builds it anyway. If coding agents are picking up tickets, they build it too.

This is the problem Thor was built for. Thor is the context infrastructure for AI-native software teams. It keeps one current record of what your team decided, changed, and left stale across Slack, GitHub, Linear, and meetings. It picks up decisions and action items from meetings and threads, links each one to where it was made, and connects it to the GitHub or Linear issue it affects. Nothing becomes official just because Thor spotted it: Thor proposes, and a person approves anything that sets a real commitment. Your coding agents can read the same record through Thor’s MCP server before they start work.

You can keep a decision log by hand with the template above, and many teams should. If you find the log falling behind the conversations, that’s the gap to look at. We’ve written more about telling which of a ticket and a Slack thread is true, and about what “context” actually means when everyone claims to have it.

FAQ

What is a decision log?

A running record of a team’s decisions. Each entry captures what was decided, why, the options considered, who decided, when, and a link to where it happened. Teams use it to stop re-arguing settled questions and to bring new people up to speed.

What should a decision log include?

At minimum: an ID, the date, the decision as one sentence, the reason, who decided, and a link to the source. Adding “options considered” and a status column (active or superseded) makes it much more useful months later.

What’s the difference between a decision log and an ADR?

A decision log is one running list covering all kinds of team decisions. An architecture decision record (ADR) is a separate short document for each technical decision, usually stored in the code repo. Many teams use ADRs for big architecture choices and a decision log for everything else.

Where should a decision log live?

Wherever your team already looks: a Confluence or Notion page, a Google Doc, a spreadsheet, or a markdown file in the repo. Pick one place and link to it from your tickets. A log split across tools stops being used.

How do you keep a decision log up to date?

Give it an owner, log decisions the day they’re made, and link every entry to its source. The usual failure is decisions made in Slack or meetings that never get copied over. Tools like Thor can pick those up for you and ask a person to approve them.

See how Thor keeps track of what your team decided, in Slack, meetings, and tickets, without someone copying it into a log. Book a demo.