Decision logs: the file that stops the same argument in sprint three
A decision log keeps the why behind every product call. Here's the template we use, and what happened when three settled decisions came back in production.
On November 2, the client's team was clicking through the production build of a product we'd spent six months redesigning with them. Within about an hour they'd pinned three comments. Two of them asked nearly the same thing: "I thought we opted to pull this?" and "I thought we also brought up axing both of these, too?"
They had. Both were settled in mid-July, in threads on the prototype. The third comment asked about a column the build had dropped. It turned out to be the number the client bills customers on, which their team had explained in another July thread.
Nobody did anything wrong. The decisions were made, argued and recorded. They just weren't in a decision log anyone building the production app was reading, so each one came back as a question, an answer, a ticket and a change. Cheap this time, because the right people remembered. That's not a system.
What a decision log is for
Search for a decision log template and you'll find spreadsheets for project managers: what was decided, who decided it, on what date. That's fine for governance. It isn't enough for a team building with agents.
Two readers need the log more than any manager does. The first is the coding agent, which wasn't in the meeting and will happily rebuild something you removed if nothing tells it not to. The second is the next person on the team, who wasn't there either. Both need the reason, and both need to know what was tried and thrown out.
On this redesign the prototype collected 144 feedback threads over about six months, and 54 of them ended in a decision after real back and forth. Production added 86 more threads in its first 18 days. That's a lot of settled questions to carry in people's heads.
Our decision log template
Every entry gets three columns, and the third is the one most templates leave out:
Decision | Why | Tried and removed |
|---|---|---|
Lead with the item people act on, not the group it belongs to | People act on one item at a time | A grouped list with a drill-down page |
The button says how many people it reaches | The count is the decision | A generic "Send now" with the count shown elsewhere |
Keep one record type undeletable | Legal requirement on the client's side | A delete action in the row menu |
"Tried and removed" is what stops sprint three. When someone new suggests the drill-down page, the log already says we built it, and why it went. Add who decided and when, group the entries by area of the product, and keep each line short enough to scan.
Download the decision log template, a markdown file you can drop into a repo.
Where the decision log lives
A decision moves through three places. Each one matters at a different stage.
In the thread, while it's argued. We pin feedback on the live prototype with Skyelight, and the argument happens on the element it's about. One early idea was a fork on the first screen of sign-up. The client's team pushed back the same day: their admins would pick the wrong path. They came back with a better answer, and the whole exchange is on the thread, with who decided.
In the handoff, as a file. When the prototype settles, the threads get distilled into a decisions file in the package engineering receives (how we write that package). Fifty decisions in threads become a page someone can read in five minutes.
In the rules agents load every session. This is the step we skipped. A decisions file sitting in a handoff folder only works if someone opens it. Rules in CLAUDE.md or AGENTS.md, or saved as project rules in Skyelight, get read by the agent every time it starts work. Neither project had a single saved rule. All three decisions that came back in November would have fit on one line each.
What it looks like when it works
In production the client's engineer works the feedback threads with Claude Code. One thread asked why a create dialog had a field the prototype didn't. Instead of deleting it, the agent explained why the old app had it: some restricted users are only allowed to create things in certain places. It laid out options on the thread, I picked one, and the agent built it and linked the pull request. The reason now sits next to the code that depends on it.
That's the whole job of a decision log: put the why where the next builder will see it, whether that builder is a person or an agent.
A decision nobody wrote down is a decision you'll make again.