0. Architecture Decision Records: the process

• Status: Accepted
• Date: 2026-09-02

Context

Korrin's guiding constraint is that every meaningful design decision is written down when it is made, not reconstructed later from code archaeology or commit messages. "Why does / always return a float?" and "why spaces-only indentation?" are questions that must have a durable, discoverable answer.

We need a format that is:

• lightweight enough that writing one is not a chore;
• versioned alongside the code it describes;
• append-only, so the history of thinking is preserved even when a decision is later reversed.

Architecture Decision Records (ADRs), as popularised by Michael Nygard, fit exactly.

Decision

Every meaningful decision about the Korrin language or its implementation gets an ADR in docs/decisions/, named NNNN-kebab-case-title.md, using template.md.

Rules:

1. One decision per file. If a discussion produces two decisions, write two ADRs.
2. Numbers are permanent and never reused. 0007 is 0007 forever.
3. ADRs are immutable once Accepted, except to change their Status line or add a link to the ADR that supersedes them. To change a decision, write a new ADR whose "Context" explains what changed, and set the old one's status to Superseded by NNNN.
4. Status is one of: Proposed, Accepted, Superseded by NNNN, Deprecated.
5. The index lists every ADR. CI fails if a file in this directory is missing from the index or is missing a required section (Status, Context, Decision, Consequences).
6. Code cites ADRs by path in a comment whenever it implements something an ADR explains, so a reader of the code can find the reasoning.

Consequences

• A pull request that changes behaviour without either matching an existing ADR or adding a new one will be flagged in review (see the PR template).
• The docs/decisions/ directory becomes the canonical history of the language's design intent. The specification (docs/spec/) says what Korrin does; the ADRs say why.
• Some overhead per decision. Accepted as the cost of the project's core promise.

Alternatives considered

• Design notes in a wiki or issue tracker. Not versioned with the code, rots when the tool changes, invisible from a checkout.
• Rationale only in code comments. Good for local "why", but there is nowhere to record a decision that spans many files or one that is about something not in the code (a feature deliberately omitted).