adr-documentation

What this skill does

# ADR Documentation

## Overview

### What are ADRs?

Architecture Decision Records (ADRs) are lightweight documents that capture important architectural decisions along with their context and consequences. They serve as a historical record of why certain choices were made, helping teams avoid revisiting settled debates and providing context for future developers.

**Key characteristics:**
- **Immutable**: Once accepted, ADRs are rarely modified (supersede instead)
- **Context-rich**: Capture the environment and constraints at decision time
- **Outcome-focused**: Document what was decided and why
- **Alternative-aware**: Show what options were considered and rejected

### Why Document Decisions?

**Context Preservation:**
- Future team members understand *why* things are the way they are
- Avoid "we've always done it this way" without knowing the reason
- Preserve institutional knowledge across team changes

**Onboarding:**
- New developers can read ADR history to understand system evolution
- Reduces repetitive explanations of architectural choices
- Provides learning path through project decisions

**Avoiding Repeat Mistakes:**
- Document why certain approaches were rejected
- Prevent re-proposing failed solutions
- Learn from past trade-offs

**Alignment:**
- Create shared understanding across team
- Resolve disagreements with documented rationale
- Enable asynchronous decision-making

### When to Write an ADR

Write an ADR when:
- **Significant architectural choices**: Microservices vs monolith, event-driven vs request/response
- **Technology selections**: Database choice, framework adoption, language decisions
- **Pattern decisions**: State management approach, authentication strategy, error handling patterns
- **Breaking changes**: API redesigns, data model changes, migration strategies
- **Performance-critical decisions**: Caching strategies, optimization approaches, scalability patterns
- **Security-related choices**: Authentication methods, encryption strategies, access control models
- **Infrastructure decisions**: Deployment strategy, hosting platform, CI/CD approach
- **Dependency selections**: Major library choices, third-party service integrations

**Don't write an ADR for:**
- Minor implementation details
- Temporary workarounds
- Personal coding style preferences
- Reversible low-impact choices

## ADR Structure

### Standard Format

```markdown
# ADR-XXXX: [Short Title]

## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-YYYY]

## Date
YYYY-MM-DD

## Context
[Problem statement and environment]

## Decision
[What was decided]

## Consequences
[What results from this decision]

## Alternatives Considered
[Other options evaluated]

## Related ADRs
[Links to related decisions]

## References
[External links and documentation]
```

### Section Guidelines

**Title:**
- Format: `ADR-XXXX: Short Decision Title`
- Be specific: "ADR-0012: Use PostgreSQL for Primary Database"
- Not generic: "ADR-0012: Database Choice"

**Status:**
- **Proposed**: Under discussion, not yet accepted
- **Accepted**: Decision is final and being implemented
- **Deprecated**: No longer recommended but not replaced
- **Superseded by ADR-YYYY**: Replaced by a newer decision

**Date:**
- Use ISO format: YYYY-MM-DD
- Date of status change, not original proposal

**Context:**
- Describe the forces at play
- Technical constraints
- Business requirements
- Team capabilities
- Timeline pressures
- Budget considerations
- Example: "We need to store structured data with complex relationships. Team has limited database expertise. Must support 100k+ users within 6 months."

**Decision:**
- State clearly what was decided
- Include scope and boundaries
- Specify what is NOT included
- Example: "We will use PostgreSQL as our primary database for all structured data. NoSQL solutions may be used for specific use cases (caching, session storage) but PostgreSQL is the default."

**Consequences:**
- **Positive**: What benefits we gain
- **Negative**: What drawbacks we accept
- **Neutral**: What trade-offs we're making

Example:
```markdown
### Positive
- Strong ACID guarantees for transactions
- Rich query capabilities with SQL
- Mature ecosystem and tooling

### Negative
- Requires careful index management for performance
- Scaling horizontally is more complex than NoSQL
- Team needs PostgreSQL training

### Neutral
- Need to establish backup/restore procedures
- Must define connection pooling strategy
```

**Alternatives Considered:**
- List 2-4 alternatives seriously evaluated
- For each: Pros, Cons, Why rejected
- Be fair to alternatives (avoid strawman arguments)

**Related ADRs:**
- Link to decisions that influenced this one
- Link to decisions this one influences
- Create a decision graph over time

**References:**
- Documentation links
- Blog posts or articles that influenced decision
- Benchmark results
- Proof of concepts

## ADR Numbering and Naming

### Sequential Numbering

Use zero-padded sequential numbers:
- `ADR-0001`, `ADR-0002`, ..., `ADR-0010`, ..., `ADR-0100`
- Four digits handles up to 9,999 ADRs (enough for most projects)
- Don't skip numbers when superseding (new ADR gets next number)

### File Naming

Format: `ADR-XXXX-short-title.md`

Examples:
- `ADR-0001-use-postgresql-database.md`
- `ADR-0002-adopt-react-19-frontend.md`
- `ADR-0003-implement-jwt-authentication.md`

**Naming guidelines:**
- Use lowercase
- Use hyphens (not underscores or spaces)
- Keep title short but descriptive
- Include key technology/pattern name

### Location

Recommended locations:
- **Option 1**: `ai-docs/decisions/` (alongside other AI-focused docs)
- **Option 2**: `docs/adr/` (standard documentation location)
- **Option 3**: Root `adr/` directory (if ADRs are primary docs)

**Choose consistently across project.**

For Claude Code plugins:
- Use `ai-docs/decisions/` to co-locate with CLAUDE.md and other AI docs
- Makes ADRs easily discoverable by Claude

## When to Write an ADR

### Technology Adoption

**Write an ADR when:**
- Adopting a new framework or major library
- Choosing between competing technologies
- Upgrading to a new major version with breaking changes

**Examples:**
- ADR-0015: Migrate from Webpack to Vite
- ADR-0023: Adopt TypeScript for Backend Services
- ADR-0031: Use Bun Runtime Instead of Node.js

### Architectural Pattern Selection

**Write an ADR when:**
- Choosing architectural style (monolith, microservices, serverless)
- Selecting state management approach
- Defining API design patterns
- Establishing error handling strategies

**Examples:**
- ADR-0008: Use Event-Driven Architecture for Order Processing
- ADR-0012: Implement Repository Pattern for Data Access
- ADR-0019: Adopt REST over GraphQL for Public API

### Breaking Changes

**Write an ADR when:**
- Making changes that break backward compatibility
- Migrating data models
- Redesigning core APIs
- Changing authentication mechanisms

**Examples:**
- ADR-0025: Remove Legacy API v1 Endpoints
- ADR-0033: Migrate from Sessions to JWT Tokens
- ADR-0041: Change User ID from Integer to UUID

### Performance-Critical Decisions

**Write an ADR when:**
- Implementing caching strategies
- Making database optimization choices
- Selecting algorithms for hot paths
- Deciding on async vs sync processing

**Examples:**
- ADR-0017: Implement Redis for Session Caching
- ADR-0022: Use WebSockets for Real-Time Updates
- ADR-0028: Adopt Background Job Queue for Heavy Processing

### Security-Related Choices

**Write an ADR when:**
- Choosing authentication methods
- Implementing authorization strategies
- Selecting encryption approaches
- Defining security policies

**Examples:**
- ADR-0010: Use OAuth 2.0 with PKCE for Mobile Auth
- ADR-0014: Implement Row-Level Security in PostgreSQL
- ADR-0020: Adopt OWASP Guidelines for API Security

## ADR Lifecycle

### Proposal Phase

**Creating a Proposal:**
1. Draft ADR with status "Proposed"
2. Share with team for feedback
3. Discuss in team meeting or async comments