| name | adr |
| description | Generate Architectural Decision Records (ADRs) in MADR format. Invoke when the user requests an ADR or when the adr-review skill surfaces uncovered architectural decisions and the user agrees to record them. Do NOT auto-create ADRs without user approval. ADRs are written to docs/adr/ in the current git repository. |
Architectural Decision Records
Record architectural decisions as concise MADR documents in docs/adr/ within the current repo.
Workflow
- Notify early: As soon as an architectural choice is identified, tell the user an ADR will be needed. Do not wait until the end of planning.
- Collaborate on the decision: If the decision involves choices (e.g., which database, which framework), work through the options with the user before drafting. If the choice was already made during planning, confirm it.
- Draft: Write the ADR using the MADR template in references/madr-template.md
- Check supersession: Read existing ADRs in
docs/adr/ to determine if this decision supersedes a previous one
- Present: Show the draft ADR to the user for approval
- Write before implementation: On approval, write the ADR file and update OVERVIEW.md. ADRs MUST be committed before any implementation work begins.
- Verify gitignore: Ensure
docs/adr/ is not gitignored
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:
- Run
git check-ignore docs/adr/OVERVIEW.md
- If ignored, warn the user and suggest removing the relevant gitignore pattern
