Write records for decisions that need to survive

A useful decision record lets someone understand the choice without rebuilding the meeting it came from. Transcripts and chronological notes bury the conclusion under suggestions nobody adopted.

Keep the record close to whatever it affects, in a format the team will actually maintain. A Markdown file in the repo works for technical choices tied to code. Product rules might belong in a shared spec, and operational decisions next to the runbooks. Where it lives matters less than everyone knowing the one route to the current answer.

A compact record would have:

• A direct title that names the choice.
• A status like proposed, accepted, replaced or withdrawn.
• The date and the owner.
• The context that forced a decision.
• The behaviour that was chosen.
• The consequences and constraints that matter.
• Alternatives that are likely to get suggested again.
• Links to the affected contracts, the implementation and later revisions.

Keep the context factual: which systems, users and constraints were involved, and what you weren't sure about at the time. The next reader needs to know why this product made this choice under these conditions, and an essay on industry practice won't help them.

Write the decision in language someone can test. "Use robust error handling" is a wish. "Keep a failed delivery pending, store the external response, and require an explicit retry or cancellation" is behaviour. If teams have room to choose, say that too. For example, teams can pick their own internal retry library as long as they emit the shared event fields and use the same terminal states.

For alternatives, just note why a plausible option wasn't picked at the time, so the old discussion doesn't restart without context. Circumstances change, and the record should make it possible to reopen the question later.

When a new decision replaces an old one, link them both ways. The old page points to the current record, and the current record explains what changed. Search often surfaces older documents first, so if you only mark the new file, people will keep landing on the old one and following it.

Then test the record with the people who'll use it. Can a developer change the relevant code consistently from it? Can a reviewer spot a conflict? Can a future owner see which assumption would justify reopening it?