ADR Ops

An Architecture Decision Record (ADR) captures one architectural decision: what was decided, why, what was rejected, and what it costs. ADRs are append-only project memory — they exist so a future maintainer touching a subsystem can recover the reasoning behind its shape without archaeology through git history or chat logs.

This skill encapsulates a battle-tested ADR protocol and generalizes it to any repo. The default location is docs/adr/, but every script takes --dir so a repo can keep records anywhere (docs/decisions/, architecture/adr/, …).

When to write an ADR

Write one when a change has any of these properties: