# Decision log

Six months later the question is never "how does this work".
It is "why is it like this". If the answer is a Slack thread, it is gone.

One file per decision, in `docs/decisions/`. Numbered. Immutable once accepted.
To change a decision, write a new entry that supersedes the old one. Do not edit history.

---

## Template

```markdown
# DEC-{NNNN}: {short title}

Date: {YYYY-MM-DD}
Status: proposed | accepted | superseded by DEC-{NNNN}
Deciders: {names and roles — the people who will still be here}

### Context

What was true when we decided. Constraints, incident, bill, deadline.
Not the architecture. The situation.

### Decision

One paragraph. What we will do, in production, from this date.

### Consequences

What becomes easier. What becomes harder. What we now refuse to do.

### Why not the alternative

Name the option we rejected and the reason. "We didn't think of it" is not a reason.

### Review by

{YYYY-MM-DD} — or "when {event}". A decision without a review date is a habit, not a decision.
```

---

## Example (anonymised)

```markdown
# DEC-0014: Promote by digest, never by moving tag

Date: 2026-04-03
Status: accepted
Deciders: platform (A.R.), backend lead (M.S.)

### Context

Staging and production drifted for eleven days because `:prod` and `:main`
were retagged under a canary. The rollback button rebuilt `main`. `main`
had moved. The rollback shipped a different image than the one we had
just declared known-good.

### Decision

Every promotion specifies an immutable image digest. Tags are labels in
the registry, not addresses. The deploy runbook writes the digest before
and after. Rollback is `promote $PREV_DIGEST`.

### Consequences

We cannot "just rebuild". A broken build on `main` does not block a
rollback. The registry bill grows with retained digests; we keep the last
N known-good and garbage-collect the rest on a schedule.

### Why not the alternative

Moving tags (`:prod`) look simpler and make the UI one click. They also
make every rollback a rebuild, which is how we got the eleven-day drift.
Helm `latest` is the same mistake with a different name.

### Review by

2026-10-03 — or the first time a rollback takes longer than the time
budget in the runbook, whichever comes first.
```