DR-[NNN]: [Decision in a few words]

How to use this template

Copy this file for each decision and number it in order: DR-001, DR-002 and so on. A number is never reused.
Write it while the reasons are fresh: before deciding, with the status Proposed, or within a day of the decision. The status is Proposed, Accepted, Rejected or Superseded by DR-NNN.
Write for someone who joins in a year and wasn't in the room. State the context as facts, and keep the argument for the options table. List the chosen option first and mark it “(chosen)”.
Be honest about the cost: what becomes harder, what could go wrong, and the signal that should reopen the decision.
Once a record is Accepted, don't rewrite it. If the decision changes, write a new record and set this one's status to “Superseded by DR-NNN”.
Delete this box and the example when you're done.

Status
Date
Deciders
Consulted

Decision

We will [do what] because [the reason that outweighed the others].

Applies to:
Doesn't decide:

See an example

Title: DR-014: Store order events in PostgreSQL

Decision: We will store order events in an append-only PostgreSQL table, partitioned by month, because the team already runs PostgreSQL in production and our peak load of about 300 events a second is far below its limits.

Applies to: The order service and the reporting jobs that read its events.

Doesn't decide: Whether other services keep events too, or how long events are kept.

Option rejected: Kafka with a compacted topic. It handles far more volume, but it is a new system for a three-person team to run on call, for a load we don't have.

Revisit if: Peak load passes 2,000 events a second.

Context

Facts only; the argument goes in the options.

Fixed:
Trading off:
If we wait:

Options considered

Option	For	Against


Do nothing

Consequences

Easier:
Harder:
Risk to watch:
Revisit if:

Follow-ups