# Write the decision down: a one-page decision record

> Teams repeat arguments because nobody wrote down why. A decision record is one page: the context, the decision, what you rejected and what it costs. A template you can copy.

Source: https://hintvo.com/blog/write-the-decision-down | Last updated: November 20, 2026 | Reviewed: 2026-11-20

Teams repeat the same argument every six months because the decision was made in a call and the reasons lived in three people's heads. A decision record fixes that with one page: what the situation was, what you decided, what you rejected, and what it costs you.

## What goes in it

- **Context.** The problem and the constraints at the time. Future readers will not remember them.
- **Decision.** One or two sentences, stated plainly.
- **Alternatives.** What you considered and why you said no. This is the part people come back for.
- **Consequences.** What gets easier, what gets harder, what you now have to watch.

## A template

```markdown
# 12. Retries live in the queue worker

Date: 20 November
Status: accepted

## Context
A failed payment job stays failed today. Support sees about two
percent of charges fail on the first try. We want retries, and a
retry must never charge a customer twice.

## Decision
The queue worker retries a failed charge. Before any retry is added,
every charge carries a unique key per order, so a repeated request
counts as one charge.

## Alternatives
- Retry inside the charge function: hides the retry from the queue
  and makes timeouts harder to reason about.
- Let the customer retry by hand: no code, but support load stays.

## Consequences
- The worker needs a retry limit and backoff.
- The orders table gets a key column and a migration.
```

## When to write one

- The decision is expensive to reverse.
- People disagreed before it was made.
- Someone new would reasonably ask why it is this way.

A naming choice does not need one. Choosing where retries live does.

## Where to keep it

In the repository, next to the code it explains, in a folder of numbered files. A record in a wiki drifts away from the code. A record in the repository is found by the same search that finds the code.

## Never edit, only replace

When a decision changes, write a new record that says it replaces the old one, and mark the old one as replaced. The history of what you used to believe is the most useful part.

> **Where Hintvo fits:** when you stop listening, Hintvo's notes list the decisions from the call and the files the action items touch, which is most of a decision record's first draft. Meeting notes need a pack of hours. The example above follows the sample meeting on the [home page](https://hintvo.com/#replay).

## Related

- [AI meeting assistant for developers, with answers from your code](https://hintvo.com/meeting-assistant-for-developers.md): How does Hintvo AI help in sprint planning, design reviews and incident calls?
- [Meeting notes developers actually use](https://hintvo.com/blog/meeting-notes-developers-actually-use.md): What should technical meeting notes contain so that people use them?
- [How to walk a team through your pull request](https://hintvo.com/blog/walk-a-team-through-your-pull-request.md): How do I present a pull request or a code change to my team?
