# DECISIONS.md

This document defines how Architecture Decision Records (ADRs) work in Local LLC. The actual
log of decisions lives in [decisions/](decisions/) — this file is policy, that directory is the
record.

## What is an ADR

A short document capturing a decision with lasting technical consequence: something that would
be expensive or disruptive to reverse, or that future engineers need to understand the reasoning
behind rather than just the outcome. An ADR is not a design doc, a PR description, or meeting
notes — it's a permanent record of "we decided X, here's why, here's what we considered instead."

## When to write one

Write an ADR before implementing, not after, when a decision:

- Changes how multiple projects or roles interact with shared infrastructure (Gitea, ACT
  Runner, Plane conventions).
- Introduces a new architectural pattern, major dependency, or technology choice a project will
  build on.
- Reverses or significantly amends a previous ADR.
- Is flagged `needs-adr` in Plane by the Architect (`PLANE.md`).

Don't write one for routine implementation choices already covered by `CODING_STANDARDS.md` — an
ADR is for decisions that standard doesn't already settle.

## Who writes and approves them

- Any engineering role can draft an ADR when they hit a decision point that qualifies.
- The Architect approves it before it's considered accepted — this is the Architect's core
  authority per `ORGANIZATION.md`.
- Decisions with company-wide, irreversible impact (per `FOUNDER.md`'s approval table) still
  require Founder sign-off in addition to Architect approval — the Architect approving a
  technically sound ADR does not itself clear the Founder's approval gate for decisions that
  belong there.

## Process

```
1. Draft using templates/ADR.md
2. Open as a PR against decisions/ (numbered, see below)
3. Architect reviews — approves, requests changes, or rejects with reasoning
4. If it qualifies as Founder-gate territory (FOUNDER.md), get that sign-off too
5. Merge — status becomes "Accepted"
6. If later reversed, a NEW ADR supersedes it — the old one's status changes to
   "Superseded by ADR-00XX", it is never deleted or rewritten
```

## Numbering and location

Files live in `decisions/` as `NNNN-short-title.md`, numbered sequentially starting at `0001`.
Numbers are never reused, even for a rejected or later-superseded ADR — the log is append-only.
`decisions/README.md` is the index.

## Format

Use `templates/ADR.md`. At minimum: Status, Context, Decision, Consequences, Alternatives
Considered. An ADR that only states the decision without the alternatives considered isn't
useful to the next engineer who wonders "why not X instead" — include enough of the "why not"
to make that question unnecessary to re-ask.

## Relationship to project docs

A project's `PROJECT.md` (`templates/PROJECT.md`) should link the ADRs that shaped it. An ADR
is company-wide by default (in `decisions/`), even when it was motivated by one project — if a
decision is genuinely project-specific and has no bearing beyond that project, it can live in
the project's own folder instead, but default to the shared log unless there's a clear reason
not to.