adr

adr

Purpose

Create, list, update, and supersede Architecture Decision Records (ADRs) following the Markdown Architectural Decision Records (MADR) 4.0 format. Maintains an ADR directory (see Directory Convention below). Works standalone or as a companion to /architecture-design.

Directory Convention

Before creating anything, detect where this project keeps ADRs. Use Glob to check, in order: docs/decisions/ADR-*.md, docs/decisions/[0-9][0-9][0-9][0-9]-*.md, docs/adr/*.md, adr/*.md, docs/architecture/decisions/*.md. Use the first directory that already contains ADRs. Only if none exists, default to docs/decisions/. All paths below refer to this detected directory. If existing ADRs use a different file-name pattern (e.g. MADR's NNNN-title.md), follow that pattern instead of ADR-NNN-title.md.

ADR Format (MADR 4.0)

Every ADR follows the MADR 4.0.0 template (https://adr.github.io/madr/). Metadata lives in YAML front matter. tags is not part of MADR; this skill adds it as an optional key so list and search can filter by area. Sections marked <!-- optional --> may be dropped when they add nothing; remove the marker comments from the saved file.

---
status: proposed | accepted | rejected | deprecated | superseded by ADR-NNN
date: YYYY-MM-DD
decision-makers: <names or roles>
consulted: <people whose opinions were sought; two-way communication>
informed: <people kept up to date; one-way communication>
tags: <architecture | security | database | api | infrastructure | ...>
---

# ADR-NNN: <Title>

## Context and Problem Statement

[2-3 sentences: what situation led to this decision? What problem is being solved? Phrase it as a question if that helps.]

<!-- optional -->
## Decision Drivers

* [driver 1: most important constraint or goal]
* [driver 2]

## Considered Options

* [Option A]
* [Option B]
* [Option C]

## Decision Outcome

Chosen option: "[Option A]", because [justification tied to the decision drivers].

<!-- optional -->
### Consequences

* Good, because [what becomes easier, better, or possible]
* Bad, because [what becomes harder, more expensive, or is given up]
* Neutral, because [effect that is neither a gain nor a loss]

<!-- optional, but include it whenever possible -->
### Confirmation

[How compliance with this decision will be checked: design or code review, an architecture test (e.g. ArchUnit), a lint rule, a CI check.]

<!-- optional -->
## Pros and Cons of the Options

### [Option A]

* Good, because [argument]
* Neutral, because [argument]
* Bad, because [argument]

### [Option B]

* Good, because [argument]
* Bad, because [argument]

<!-- optional -->
## More Information

[Supporting evidence, team agreement, when to revisit the decision, links to related ADRs, design docs, RFCs, or tickets.]