Decision record template

A decision record template is a short page you fill in each time you make a call that others will build on. It holds the decision, why you made it, what you weighed and what would change your mind. For the term, see What is a decision log?.

TL;DR

• One record per decision that would be costly or confusing to reverse.
• Write it in minutes: decision, context, options, why, what would change it, date, owner.
• The "what would change it" line is the one most records skip, and the most useful.
• A decision becomes a principle when you write it as a rule every agent can follow.
• Skip small calls. A log nobody reads is worse than none.

When to use it: you keep re-deciding the same thing, or an agent built something you had already ruled out. When not: reversible, low-stakes choices you can undo this afternoon.

A decision record template

The format follows the architecture decision record idea, which Michael Nygard described in 2011, trimmed for product decisions. Copy it and fill it in.

# Decision record: [title]

Inputs: a decision just made, the evidence, the options.
Outputs: this record, plus a one-sentence principle if the rule should apply again.

- Decision: [one sentence, present tense]
- Context: [what was true: the problem, the evidence, the constraint. 3 sentences.]
- Options considered:
  1. [option]: [what it would cost]
  2. [option]: [what it would cost]
  3. Do nothing: [what that costs]
- Why: [the evidence and the trade you accepted]
- What would change it: [the fact that makes you revisit]
- Date: [date]
- Owner: [name]
- Status: [proposed | accepted | replaced by [link] | dropped]

## Principle (optional)
Rule: [one sentence, as an instruction]
Reason: [a few words, so an agent can handle the edge case]
Record: [link to this page]
Put it where every agent reads it.

How do I fill it in?

Decision. One sentence, in the present tense. "We do not build a mobile app this year." Not "we are considering".

Context. What was true when you decided: the problem, the evidence, the constraint. Three sentences. Someone reading in six months should see why this was a real question.

Options considered. The two or three real choices, including "do nothing". One line each on what it would have cost.

Why. The reason you chose this one. Name the evidence and the trade you accepted. "Cheaper" is a reason only if you say what you gave up.

What would change it. The fact that would make you revisit. "If three paying accounts ask for it" or "if the sign-up rate drops below X". This keeps a decision from hardening into a habit.

Date and owner. When it was made and by whom. Decisions without an owner have no one to ask.

Status. Proposed, accepted, replaced or dropped. When a decision is replaced, link the new one.

How do I turn a record into a principle?

A record explains one decision. A principle is a rule that comes out of it, short enough that any agent can follow it without reading the history.

1. Look for a decision you made twice, or one an agent would otherwise repeat.
2. Write the rule in one sentence, as an instruction: "Do not add features that need a second sign-in."
3. Add the reason in a few words, so the agent can handle the edge case.
4. Put it where every agent reads it: your shared rules file, or a saved principle in your product's memory.
5. Link the record, so the evidence stays with the rule.

Keep the list of principles short. Ten good ones beat fifty that nobody checks. For how memory works across sessions, see AI agent memory.

An example, filled in

This is an example, made up to show the level of detail. Say a four-person team with 40 customers.

• Decision: We do not build a mobile app this year.
• Context: Three customers asked for one. All three use the product on a laptop and asked after a trip, to check things from a phone. Our two bets this quarter are "keep paying customers" and "win more trials", and neither needs mobile.
• Options considered: (1) Build a native app: months of work for four people. (2) Make the web app work on a phone: a few weeks. (3) Do nothing.
• Why: Option 2 answers all three requests at a fraction of the cost. We accept that offline use will not work.
• What would change it: Five paying accounts ask for offline use, or trial sign-ups from phones pass a quarter of the total.
• Date and owner: 21 Oct, Priya.
• Status: Accepted.

Principle: Make things work on a phone before building anything native. (Reason: the team is small and the requests were about reading, not offline use. See the decision on 21 Oct.)

Notice the principle is one sentence, with the reason in brackets. An agent that reads it will not propose a native app, and will know when to ask if something looks like an exception.

What mistakes should I avoid?

• Recording every choice. Only record what would be costly or confusing to reverse.
• Leaving out the options. Without them, the decision looks obvious and nobody remembers the alternative.
• No "what would change it". The decision turns into a rule nobody can question.
• Writing after the fact, from memory. Write it the day you decide.
• Principles that are really essays. If it takes a paragraph, split it or cut it.
• Keeping the principle somewhere agents do not look. A rule only your head knows is not a rule.

How does Annsa do it?

Annsa keeps your decisions where every agent reads them. Save one as a principle and you answer once. Agents can propose a principle over MCP with annsa.decide, but a person approves it. Principles sit beside your priorities, so the reason behind the call stays with the work. See how memory works and decisions and principles.