ADR-NNNN: <Short decision title>
Context
Section titled “Context”What problem are we deciding? What forcing functions triggered this decision now? What constraints bound the solution space (hardware, memory, latency, team bandwidth, in-flight work)?
Include a “Forcing functions” subsection if the timing matters — why now, not last month, not next sprint.
Include a “Constraints” subsection if the decision is shaped by immovable boundaries.
Decision
Section titled “Decision”One paragraph, then numbered list of concrete commitments. State what we will do, not what we might do. Reference specific files, functions, types, memory budgets, versions.
Options Considered
Section titled “Options Considered”Option A:
Section titled “Option A: ”What it is. Why considered. Rejected because … or Chosen because …
Option B:
Section titled “Option B: ”…
Option C:
Section titled “Option C: ”…
Mark the chosen option *(ACCEPTED)* in its heading.
Trade-off Analysis
Section titled “Trade-off Analysis”Why the chosen option wins against each alternative on the dimensions that matter for THIS decision (perf, authoring surface, memory, complexity, migration cost, risk, time-to-ship). Be honest about what the chosen option costs us.
Consequences
Section titled “Consequences”Positive
Section titled “Positive”- …
Negative / Accepted costs
Section titled “Negative / Accepted costs”- …
Follow-on work this ADR creates
Section titled “Follow-on work this ADR creates”- …
Documentation Updates (REQUIRED — part of the decision, not aspirational)
Section titled “Documentation Updates (REQUIRED — part of the decision, not aspirational)”List every doc, spec, source file, and README that must change to match this ADR. The audit agent enforces this list on every scheduled run. Failure to update these is treated as a live contradiction.
-
CLAUDE.md— section(s) to update -
docs/<path>.md— section(s) to update -
kn86-emulator/src/<file>.h|c— comment, constant, or signature to update -
README.md— if public-facing behavior changed -
docs/KN-86-Platform-Design-Master-Index.md— if a new DEFINITIVE doc exists -
docs/DEFINITIVE-ARTICLES.md— if the canonical set changed - Archive any doc made obsolete →
docs/_archive/<original-path>with banner
A PR that lands an ADR without ticking these boxes fails review.
Narrative (for the design history)
Section titled “Narrative (for the design history)”One paragraph in plain English that a non-expert could read in the Definitive Guide. What changed, what we believed before, what we believe now, and why a future reader should care. This is the piece that makes the ADR sequence a readable story.