Architecture Decision Records

Expert guidance for creating and managing Architecture Decision Records based on Olaf Zimmermann's research and the MADR (Markdown Architectural Decision Records) methodology.

How This Skill Works

When invoked, this skill guides you through the full ADR lifecycle:

1. Readiness assessment — Evaluate whether a decision is ready to be recorded (START criteria)
2. Creation — Write well-structured ADRs using the MADR template with anti-pattern avoidance
3. Quality evaluation — Check completeness using the ECADR "Definition of Done" criteria
4. Lifecycle management — Maintain ADR logs, supersede outdated records, track decision status

Core Philosophy

"Don't decide too early, this harms flexibility. Don't decide too late either."

ADRs function as decision journals — not blueprints or policies. They capture the rationale behind architecturally significant choices: the problem context, the alternatives considered, the criteria applied, and the consequences accepted. Good ADRs are executive summaries that balance tradeoffs, not sales pitches for a predetermined outcome.