ADR

Type: kb/types/type-spec.md

Authoring Instructions

Use an ADR for a concrete architectural decision that has been made and implemented — accepted, superseded, or deprecated. A decision still under consideration is not an ADR; it stays in the workshop layer (kb/work/) until decided.

Frontmatter

Field	Required	Use
description	Yes	Discriminating retrieval description for the decision record.
type	Yes	../types/adr.md for ADR files under kb/reference/adr/.
tags	No	Navigation tags, usually empty for ADRs.
status	No	Decision lifecycle: accepted, superseded, or deprecated.

• The title should start with the numeric ADR prefix used in this collection, then a short decision label.
• Status records the decision lifecycle, not the note-writing status.
• Date is the decision date.
• Context explains the pressure or problem that forces a choice.
• Decision states the actual choice, not the surrounding debate.
• Consequences should name what becomes easier, harder, riskier, or no longer possible as a result, and — in its own paragraph — where the decision stops applying: the conditions outside which it has not been tested or should not be extended. A limit stated separately can be narrowed by a later revision without reopening the decision.
• For decisions dated 2026-07-25 or later, the ADR must carry a ## Considered alternatives section: the options weighed and why each lost, the forces that decided, and any free choices resolved or deliberately left open. A commitment recorded without its alternatives cannot be audited or revisited — and once the design work behind it is archived, the ADR is the only frontier carrier of that reasoning (ADR 056). Compress: a paragraph per option, not the option's full text. "None developed" is admissible content and is itself information about how the decision was reached. ADRs dated earlier predate this requirement and are not retrofitted; 044 and 045 were retrofitted as ADR 056's worked cases.
• An ADR retains what revising the decision needs and leaves the change narrative to git (ADR 074). Context states the forces that would recur if the decision were reverted, not the before-state as a diff. Do not record migration steps, inventories of files touched, implementation details recoverable from src/commonplace/, or which documents were edited to match; those are in the implementing commits. Before revising or superseding an ADR, read git log --grep='ADR 0NN' for the commits that implemented or later touched it; if the clone is shallow (git rev-parse --is-shallow-repository), run git fetch --unshallow first — the measurements behind a decision live in those commits (ADR 074).
• For decisions dated 2026-07-24 or later, the ADR must also name the decision's operativity path: what consumes the changed organization, through which channel, and with what force — in Consequences, or in Decision when the path is itself part of the choice. A decision without a named consumer is recorded but inert, and the record is where that should become visible. ADRs dated earlier predate this requirement and are not retrofitted.

Template

---
description: Template for architecture decision records — implemented decisions with Context, Decision, Considered alternatives, and Consequences sections
type: ../types/adr.md
tags: []
status: accepted
---

# {NNN}-{decision-title}

**Status:** {accepted | superseded | deprecated}
**Date:** {YYYY-MM-DD}

## Context

{Context}

## Decision

{Decision}

## Considered alternatives

{Options weighed and why each lost; the deciding forces; free choices resolved or left open}

## Consequences

{Consequences}

---

Relevant Notes:

• Operative change — rests-on: the operativity-path requirement — a decided change reaches later behavior only through a consumer, channel, and force
• Where change candidates come from in Commonplace — evidenced-by: instrumented ADRs are the ongoing evidence stream for how the system's organization actually changes