Adr

File Conventions

• Location: docs/adr/ at the repo root (create if missing via mkdir -p)
• Filename: YYYYMMDD_<subject>.md — use today's date, lowercase snake_case subject
  • Example: 20260224_use_postgresql_for_persistence.md
• OVERVIEW.md: docs/adr/OVERVIEW.md — always regenerate after writing/superseding an ADR

Conciseness Rules

ADRs MUST be as short as possible. Target guidelines:

• Context: 2-3 sentences max
• Decision Drivers: 2-4 bullets
• Options: 2-4 options, one line each in the Considered Options list
• Decision Outcome: 1-2 sentences
• Consequences: 2-4 bullets total
• Pros/Cons: Only include if the tradeoff is non-obvious; omit if Decision Outcome justification is sufficient

Supersession

• When a new ADR supersedes an existing one, set supersedes: YYYYMMDD_<subject>.md in the new ADR's frontmatter
• Update the superseded ADR's frontmatter status to superseded by YYYYMMDD_<subject>.md
• ADRs merged into the default branch are immutable — never edit their content, only update the status field when superseded

OVERVIEW.md Format

Regenerate the full file each time. List only active (non-superseded) ADRs:

# Architectural Decision Records

| Date | Decision | Supersedes |
|------|----------|------------|
| YYYY-MM-DD | [Short title](YYYYMMDD_<subject>.md) | [Previous title](YYYYMMDD_<prev>.md) or — |

Gitignore Check

After writing, verify docs/adr/ is not excluded:

1. Run git check-ignore docs/adr/OVERVIEW.md
2. If ignored, warn the user and suggest removing the relevant gitignore pattern