SKILL.md
Architecture Decision Record (ADR)
An Architecture Decision Record documents a significant technical decision along with its context and consequences. ADRs capture the "why" behind architectural choices so future team members understand the reasoning - especially important when they question why something was done a particular way. This skill follows Michael Nygard's lightweight ADR format.
When to Use
- Making significant technical decisions that affect system architecture
- Choosing between technology options (frameworks, databases, services)
- Establishing patterns that future development should follow
- Documenting the rationale for constraints or non-obvious approaches
- Preserving institutional knowledge about past decisions
When NOT to Use
- The decision is a product or UX design choice, not architecture or technology -> use
develop-design-rationale - You are still exploring whether an approach is feasible -> time-box the exploration and record it with
develop-spike-summaryfirst - You need to pitch a solution to stakeholders -> use
develop-solution-brief; an ADR records a decision, it does not sell one - Nothing is actually being decided (the status quo continues unchanged): an ADR without a decision is noise; wait until there is one