adr

Architecture Decision Record (ADR) — Philosophy-First

ADRs capture the context, reasoning, and consequences of significant technical decisions. They serve as institutional memory — when someone asks "why did we do it this way?" six months from now, the ADR has the answer.

This skill uses a 3-phase process inspired by the canvas-design principle: define the vision before the implementation. Every architectural decision should align with a declared architectural identity, not just solve an immediate problem.

When to Write an ADR

An ADR is warranted when:

• Choosing between frameworks, libraries, or services
• Defining API contracts or data models
• Deciding on infrastructure or deployment strategy
• Changing architectural patterns (monolith → microservices, REST → GraphQL, etc.)
• Making decisions that are costly to reverse
• Any decision where the team debated multiple options

---

Phase 1: Architectural Identity (Philosophy-First)

Before any technical decision, define what the system MUST BE.

This is the most important phase. Most teams skip it and jump to "should we use X or Y?" without first answering "what kind of system are we building?" The Architectural Identity is the compass that guides all decisions.

Architectural Identity Template

# Architectural Identity: [System Name]

## Quality Attributes (ranked by priority)
1. [Most important] — e.g., "Reliability: 99.99% uptime, zero data loss"
2. [Second] — e.g., "Security: SOC2 compliant, zero trust"
3. [Third] — e.g., "Developer Velocity: <15min deploy, <5min local setup"
4. [Fourth] — e.g., "Scalability: handle 10x current load without re-architecture"
5. [Fifth] — e.g., "Cost Efficiency: <$X/month cloud spend"

## Trade-off Declaration
"When [quality A] conflicts with [quality B], we choose [A]."
- "When reliability conflicts with velocity, we choose reliability."
- "When cost conflicts with developer experience, we choose developer experience."

## Non-Negotiables (hard constraints)
- [Constraint 1] — e.g., "All data at rest must be encrypted (AES-256)"
- [Constraint 2] — e.g., "No vendor lock-in on core business logic"
- [Constraint 3] — e.g., "All changes must be deployable independently"

## Architectural Style
[Describe in one paragraph the architectural vision]
Example: "A modular monolith with clear domain boundaries, designed to be split into services only when team scaling demands it. Event-driven communication between modules via internal event bus, with synchronous APIs only at the edge."