Skip to main content

ADR-XXXX — Short imperative title

Copy this file to docs/architecture/decisions/XXXX-short-slug.mdx, fill it in, add a row at the top of the decision table, and add it to apps/docs/sidebars.ts.

:::danger Ask before you write it There is no status field — a record in the log is a decision we have made. So the confirmation happens before the record exists: ask @mattmoran56, get an answer, then write it down. An agent must never decide one of these on its own. See the decision log. :::

DateYYYY-MM-DD
Supersedes—
Superseded by—

Context​

What forced a decision. The constraint, the problem, or the thing that stopped working. Be concrete: "we need X because Y happens at Z" beats "we should consider our options for X".

If there is a measurement, a limit, or a real incident behind this, put it here.

Decision​

What we are doing, in the present tense and as few words as possible.

We will use X for Y.

Then the specifics that a reader would otherwise have to reverse-engineer from the code.

Consequences​

What this costs. Not "the benefits" — the benefits are why you chose it and they belong in Decision. This section is for what future-you will trip over.

  • What gets harder. Be honest. Every decision closes doors.
  • What we are now committed to. Lock-in, migrations that become expensive, platforms we cannot easily leave.
  • What has to be built because of this. Follow-on work this creates.
  • How we would reverse it, and roughly what that would cost.

Alternatives considered​

The ones that were genuinely on the table, with the reason each was not chosen. One paragraph each. A rejected alternative documented here does not have to be re-argued in six months.

Alternative A​

What it was, and why not.

Alternative B​

What it was, and why not.

Open questions​

Anything this decision does not settle, and what would settle it. Better here than discovered later. If one of these turns out to need its own decision, that is a new ADR — and a new conversation before it is written.

  • Links to the documentation pages this decision shapes
  • Links to related ADRs