Document Architectural Decisions with ADRs

This skill provides expertise in creating Architecture Decision Records (ADRs) - structured documents that capture important architectural decisions made during software development, preserving institutional knowledge, easing team communication, and providing historical context for technical decisions. The core ADR structure follows a standardized format: a title, a Status field (Proposed, Accepted, Deprecated, or Superseded by ADR-XXX), a Context section describing the forces at play (technical, political, social, and project-local factors), a Decision section stating the architectural choice and its rationale, and a Consequences section describing both positive and negative resulting effects. Key principles: immutability (accepted ADRs aren't edited, they're superseded), atomicity (each ADR covers one architectural decision), sequential numbering for chronological order, and clear traceability links between related ADRs.

Core ADR components include title formatting (imperative mood and specificity, e.g. "Adopt GraphQL for the API Gateway" rather than "Database decision"), a status lifecycle (Proposed to Accepted to Deprecated/Superseded, with each status's meaning defined), and Context section best practices (business requirements and constraints, technical constraints and current architecture, team expertise and organizational factors, performance/security/scalability requirements, and timeline/budget considerations). A complete worked example demonstrates adopting GraphQL for an API Gateway: a Context section quantifying the current pain (8-12 API calls per page load, 2.3s average load time, 30% of frontend dev time spent debugging integration), a Decision section describing the Apollo GraphQL federation approach and incremental migration plan, a Consequences section with concrete positive effects (API calls reduced to 1-2, ~60% payload reduction) and negative effects (learning curve estimated at 2 sprints, caching complexity, query-cost risk), a Risks and Mitigations section (e.g. query-complexity attacks mitigated by depth limiting and cost analysis), and Related Decisions links (supersedes/relates-to other ADR numbers).

Advanced ADR patterns include decision trees for complex choices - a comparison matrix scoring multiple options (e.g. GraphQL vs REST+BFF vs gRPC) across criteria like learning curve, performance, ecosystem maturity, and team expertise - and documenting architectural spikes for decisions requiring proof-of-concept work, capturing spike duration, prototype location, and key quantified findings.

Use this skill when a significant architectural decision needs to be documented for future reference - a technology choice, a pattern adoption, or a major system design change with real trade-offs to record. It is well suited to decisions with lasting impact that future team members will need context on. It is not meant for minor implementation details with no lasting architectural significance, or for decisions still under active debate with no chosen direction yet.

Input: the architectural decision being made, its context/constraints, and the options considered.

Output: a complete ADR document with status, context, decision, consequences, risks/mitigations, and related-decision links. Example ADR structure:

# ADR-001: [Decision Title]

[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]

[Forces at play - technical, political, social, project-local]

[The architectural decision and its rationale]

[Resulting context, positive and negative]
```

Produces standalone Markdown ADR documents meant to live in a project's docs/adr directory or wiki; it does not connect to a specific documentation platform itself.

Software architects and tech leads documenting significant architectural decisions, and teams that need a searchable historical record of why past technical choices were made.