adr-writer

# Architecture Decision Record (ADR) Skill

This skill provides guidelines for creating **Architecture Decision Records** - structured documentation of significant architectural decisions.

## Purpose

ADRs capture **important architectural decisions** along with their context, alternatives considered, and consequences. They create a historical record of why things are built the way they are.

## User Need

> "Why did we decide to do it this way?"

## Characteristics

| Attribute | Description |
|-----------|-------------|
| **Orientation** | Decision documentation |
| **Focus** | Context, decision, consequences |
| **Goal** | Record rationale for future reference |
| **Tone** | Objective, comprehensive |

## Target Directory

Place ADRs in: `docs/architecture/` with naming convention `ADR-NNN-short-title.md`

## Writing Guidelines

### DO

- State the context and problem clearly
- Document all alternatives considered
- Explain why alternatives were rejected
- List both benefits and drawbacks
- Include implementation notes
- Use consistent status labels
- Number ADRs sequentially

### DON'T

- Skip the context section
- Omit alternatives that were considered
- Hide drawbacks of the chosen approach
- Forget to update status when decisions change
- Write ADRs for trivial decisions

## When to Write an ADR

- Choosing between competing technologies
- Establishing patterns that will be reused
- Making breaking changes to existing systems
- Decisions that are costly to reverse
- Decisions that affect multiple teams or components

## Examples of Good ADRs

- "ADR-001: Use PostgreSQL for primary database"
- "ADR-002: Adopt microservices architecture"
- "ADR-003: Implement event sourcing for audit log"
- "ADR-004: Choose React for frontend framework"
- "ADR-005: Use JWT for API authentication"

## ADR Status Values

| Status | Meaning |
|--------|---------|
| **Proposed** | Under discussion, not yet decided |
| **Accepted** | Decision made and in effect |
| **Deprecated** |