rdbms-playground/docs/adr/0000-record-architecture-decisions.md

ADR-0000: Record architecture decisions

Status

Accepted

Context

The RDBMS Playground project will accumulate design decisions as it grows. We want those decisions to be traceable, reviewable, and easy to challenge later when context has changed.

Decision

Record significant architecture and product decisions as Architecture Decision Records (ADRs) in docs/adr/, using the Michael Nygard format (Status, Context, Decision, Consequences). Files are numbered sequentially with a four-digit prefix and a kebab-case slug, e.g. 0001-language-and-tui-framework.md.

Each ADR captures one decision. Superseding a decision means adding a new ADR that references the old one and marking the old one as "Superseded by ADR-NNNN".

ADRs document decisions, not speculation. An idea under discussion belongs in conversation, an issue, or a design note — not an ADR. An ADR is written once a decision has actually been made.

Index discipline

docs/adr/README.md contains the canonical index of all ADRs. Whenever an ADR is added, renamed, or has its status changed (e.g. "Superseded by ADR-NNNN"), the index MUST be updated in the same change. An ADR change without a corresponding index update is incomplete.

The index lists ADRs in numerical order. Each entry shows the number, title, and — where relevant — status annotations such as "Superseded by ADR-NNNN" or "Deprecated".

Numbering discipline

ADR numbers are a single global sequence, so two branches can each grab "the next number" independently and collide on merge. (This happened when the website branch's ADR-0042 met main's ADR-0042, resolved by renumbering the former to ADR-0044.) To prevent it:

Assign an ADR's number at merge-to-main, not at creation. While the work lives on a non-main branch, draft the ADR under a placeholder — an ADR-XXXX title and a draft-<slug>.md filename — and reference it that way from any plan or notes. Give it the next free number only when the branch merges to main, renaming the file and updating its references in the same step.

A number is "taken" only once it appears in main's docs/adr/README.md, which is the single source of truth for the next free number — never compute "next" from a feature branch. A branch that genuinely needs a real number up front may instead reserve one by landing a stub index entry on main first, but placeholder-until-merge is the default.

Out-of-scope discipline

ADRs (and the plans they spawn) lean heavily on "out of scope" language. The phrase carries two very different meanings, and conflating them misleads a later reader:

• Deferred — out of scope for this plan / phase / step, but a reasonable thing to do later. A sequencing decision, effectively a tracked TODO. Where possible, point at where it will be picked up.
• Rejected — considered and deliberately not done, on principle. Durable. State the reason.

When writing an out-of-scope item, say which kind it is — e.g. OOS (deferred) / OOS (rejected: <reason>), or the equivalent in prose — so a future reader can tell a standing decision from a not-yet. A bare "out of scope" is ambiguous and tends to read, wrongly, as permanent. (Motivating example: ADR-0030 §13 OOS-2 was a deferred scope exclusion that read as a permanent rejection until ADR-0039 lifted it.)

Consequences

• New significant decisions require an ADR before or alongside the implementation that depends on them.
• Old decisions remain visible even after they are superseded.
• Reviewers can audit the rationale chain by reading docs/adr/ in order.
• The index in README.md stays trustworthy because keeping it current is part of every ADR change, not an afterthought.