
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
# 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.