# Architecture Decision Checklist

**Decision:** _______________  **Date:** _______  **Decider:** _______

> Use this for decisions that are expensive to reverse. Most decisions are not, and applying
> this to them is its own kind of waste.

## 1. What is actually being decided

- [ ] **The decision stated in one sentence**
- [ ] The problem it solves, in the language of the business
- [ ] Why now — what changed, or what is about to
- [ ] Who is affected, including teams not in the room
- [ ] **Is this reversible?** If yes, decide quickly and move on

## 2. The requirement, in numbers

- [ ] Expected load, and expected growth — measured, not assumed
- [ ] Latency requirement stated as a percentile
- [ ] Availability requirement, and what an hour of downtime actually costs
- [ ] Data volume now and in two years
- [ ] Consistency requirement: **must this be correct immediately, or eventually?**

> Most architecture arguments are two people assuming different numbers. Write them down and
> half of them end.

## 3. Options

- [ ] **At least two real options**, plus doing nothing
- [ ] The simplest thing that could work is one of them
- [ ] Each option's cost: build, run, and to operate at 3am
- [ ] Each option's failure modes
- [ ] What each rules out later

## 4. Reversibility

- [ ] How long to reverse this, honestly
- [ ] What would have to change: code, data, contracts, other teams
- [ ] Can it be trialled on a slice first?
- [ ] **If it is one-way, what evidence would change the decision?** Gather it first

| | Reverse in |
|---|---|
| Data model and its meaning | Months to years |
| Service boundaries | Months |
| Synchronous vs asynchronous between components | Weeks to months |
| A dependency that leaks into every module | Months |
| A library used behind one interface | Days |

## 5. Failure

- [ ] What happens when each dependency is **slow**, not only down
- [ ] Blast radius: what else fails when this does
- [ ] Is failure contained, or does it propagate to callers?
- [ ] What degraded operation looks like, and whether users can tell
- [ ] Whether a fallback exists, and **whether it has been tested**

> Silent degradation into stale or partial results is worse than an error, because it is acted
> on.

## 6. Data

- [ ] **One system owns each piece of data** — named
- [ ] Where copies exist, how stale they may be, and who says so
- [ ] What happens when two sources disagree
- [ ] Retention and deletion, including from copies
- [ ] Personal data identified, and its residency requirement

## 7. Operating it

- [ ] How you will know it is working — not that it is running
- [ ] What alerts, and who they wake
- [ ] How a problem is diagnosed at 3am by someone who did not build it
- [ ] Runbook for the failures you can predict
- [ ] Skills needed to run it, and whether the team has them

## 8. Cost

- [ ] Build cost
- [ ] Running cost at expected load
- [ ] Running cost at ten times expected load
- [ ] Cost of the people needed to operate it
- [ ] **What is stopped or delayed to do this**

## 9. What is being given up

- [ ] Options this closes
- [ ] Complexity added, and who pays it
- [ ] The team that inherits this in two years
- [ ] Accepted risks, named

## 10. Record it

- [ ] Decision, context, options considered, consequences — written down
- [ ] **Why the alternatives were rejected** — the most valuable part, and the most often
      omitted
- [ ] Stored with the code, not in a document nobody will find
- [ ] Dated, with the decider named
- [ ] What would prompt revisiting it

> In two years the question will be "why did they do it this way". A record that lists only
> the chosen option cannot answer it.

## Sign-off

| | Name | Date |
|---|---|---|
| Proposed by | | |
| Reviewed by | | |
| Decided by | | |