Skip to main content

Exceptions & Decision Records

Guardrails​

  • ADRs (1–2 pages) required for any non‑trivial arch/security/DX change
  • RFCs for larger cross‑repo changes
  • Reviews by Architecture Guild (CODEOWNERS on /docs/adr/*); 48h SLA
  • Exception spikes time‑boxed to ≤ 2 days with rollback plan
  • Status lifecycle: proposed → accepted → deprecated → superseded

ADR frontmatter template:

---
status: proposed
id: 0001
slug: /adr/0001-sample
---
# Title

## Context
What problem are we solving and why now?

## Decision
What is the chosen approach? Link to POCs, code, benchmarks.

## Consequences
Pros/cons, risks, tradeoffs, migration plan.

## Alternatives Considered
Briefly list rejected options and why.

LLM Notes​

  • When asked to introduce a new tool outside the paved path, generate an ADR draft instead of changing the stack directly.