Architecture Decision Records¶
An Architecture Decision Record (ADR) captures a material, hard-to-reverse architecture or policy decision: the context that prompted it, the decision itself, its consequences, and the alternatives that were considered and not chosen. ADRs exist so that future readers — human or AI — understand not just what was decided but why, without needing to reconstruct the reasoning from scratch or ask the original decision-maker.
When an ADR is required¶
An ADR is required for a decision that is material and hard to reverse — the kind of decision described in docs/governance/change-management.md. Examples: choosing where canonical documentation lives (ADR-0001), defining the scope of this repository (ADR-0002), or establishing a structural model that many other documents will depend on (ADR-0003). A minor, easily-reversible choice (e.g., wording of a single document) does not need an ADR — a work log entry or ordinary edit is sufficient.
Numbering¶
ADRs are numbered ADR-NNNN with a zero-padded 4-digit sequence number, assigned in creation order. Numbers are never reused or renumbered, even if an ADR is later superseded — see docs/standards/naming-standard.md.
Status¶
At the time of writing, every ADR in this repository carries status: proposed — each represents a decision made during this repository's founding session, not yet formally ratified through a human review checkpoint. See docs/architecture/artifact-lifecycle.md for what happens as a document moves toward approved.
Current ADRs¶
| ADR | Title |
|---|---|
| ADR-0001 | Git as Canonical Documentation Source |
| ADR-0002 | Company-Level Repository Scope |
| ADR-0003 | Layered Company/Venture/Product Inheritance |
| ADR-0004 | Separate Human and AI Documentation |
| ADR-0005 | Independent Venture Brand Architecture |
| ADR-0006 | Notion as Management, Not Canonical Source |
| ADR-0007 | Implementation Repository Boundary Remains Open |
| ADR-0008 | Private and Proprietary Default |
Writing a new ADR¶
Start from adr-template.md. Assign the next unused ADR number, use the standard document metadata front matter with document_type: record, and set status: proposed until a human owner formally approves it.