diff --git a/docs/adr/README.md b/docs/adr/README.md index 4e398550..e6d17c20 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -4,32 +4,44 @@ This folder contains Architecture Decision Records (ADRs) for the Laputa app. ## Format -Each ADR is a Laputa-compatible markdown note with YAML frontmatter: +Each ADR is a markdown note with YAML frontmatter. Template: ```markdown --- type: ADR id: "0001" title: "Short decision title" -status: active # active | superseded | proposed +status: proposed # proposed | active | superseded | retired date: YYYY-MM-DD superseded_by: "0007" # only if status: superseded --- ## Context -What situation led to this decision? What forces were at play? +What situation led to this decision? What forces and constraints are at play? ## Decision -What was decided? State it clearly in one or two sentences. +**What was decided.** State it clearly in one or two sentences — bold so it stands out. -## Alternatives considered -- **Option A** (chosen): pros / cons -- **Option B**: pros / cons -- **Option C**: pros / cons +## Options considered +- **Option A** (chosen): brief description — pros / cons +- **Option B**: brief description — pros / cons +- **Option C**: brief description — pros / cons ## Consequences -What becomes easier or harder as a result of this decision? -What triggers re-evaluation of this decision? +What becomes easier or harder as a result? +What are the positive and negative ramifications? +What would trigger re-evaluation of this decision? + +## Advice +*(optional)* Input received before making this decision — who was consulted, what they said, when. +Omit if the decision was made unilaterally with no external input. +``` + +### Status lifecycle + +``` +proposed → active → superseded + ↘ retired (decision no longer relevant, not replaced) ``` ## Rules