Decision Log Template

A decision log is the record of choices that closed an option — what you decided, what you rejected, and what would justify reopening it. It is append-only, it lives next to the work, and it exists for one reader: the person eight months from now who has the opposite instinct and cannot ask you why.

When you need one

Start one the first time a debate arrives for the second time. That is the signal — not team size, not process maturity. A team that has never relitigated anything does not need this yet.

Skip it for decisions nobody would argue with. The failure mode is not too few entries, it is a log that tried to record everything, became a chore, and got abandoned in six weeks. A handful of entries a quarter is a healthy log.

If you are writing the spec rather than the decision behind it, the Standard PRD template is the other document.

The template

# Decision log — [product or area]

Newest first. Append only: never edit a past entry, supersede it.

---

## [YYYY-MM-DD] — [The decision, as a statement]
**Status:** accepted | superseded by [date/title]
**Decided by:** [name]

**Question:** [What was actually being decided, as a question. One line.]

**Decision:** [One sentence, in the indicative. Not "we leaned toward".]

**Why:** [The constraint that forced it — something a future reader can check
is still true. If there was no constraint and you picked one to stop the
debate, say exactly that.]

**Rejected:**
- [Option] — [the specific reason, one line]
- [Option] — [the specific reason, one line]

**Revisit if:** [The condition that would make this worth reopening. A
checkable fact, not "if circumstances change".]

---

## [YYYY-MM-DD] — [Previous decision]
...

Section by section

Question

Why

The field that decides whether the entry is worth anything in a year.

Rejected

Revisit if

Status

Worked example

A weak entry and a strong one, same decision:

Weak. 2026-06-14 — Invite limits We talked about invite limits and decided to keep them conservative for now. We may revisit later.

Nothing is checkable. "Conservative" is not a number, no alternative is named, and "may revisit later" is not a condition. In eight months this entry answers no question anyone will have.

Strong. 2026-06-14 — Workspace invite limit is 20 Status: accepted · Decided by: Dewi Question: How many members can a workspace invite before billing has to support it? Decision: The limit is 20 per workspace. Why: The seat model cannot express per-seat proration above the plan cap, so anything higher produces invoices Finance has to correct by hand. Rejected: 50 — billing cannot invoice it. Unlimited — no ceiling on support load or abuse. Revisit if: billing ships per-seat proration, or we move to usage pricing.

Same decision, same five minutes to write. The second one ends the argument when it returns — or opens it correctly, if proration has since shipped.

Common mistakes

Recording everything. The fastest way to abandon a log. Record decisions that closed an option; skip the ones nobody would argue with.

Writing it later. A record written a week after the fact is a justification, not a record — you are reconstructing reasoning you no longer have, and you will reconstruct the flattering version.

Editing instead of superseding. Deletes the path, which was the entire asset.

Consensus theatre. Listing everyone who agreed makes the decision socially expensive to reverse, which is the opposite of what a good record does.

Keeping it somewhere else. A log in a separate wiki is a log nobody opens. Next to the specs, in the tool where the work already happens.