adr-writer

What this skill does

# 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** | No longer applies, but kept for history |
| **Superseded** | Replaced by another ADR (link to it) |

---

## Template

Use this template when creating an Architecture Decision Record:

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

*Date: [YYYY-MM-DD]*
*Status: [Proposed | Accepted | Deprecated | Superseded by ADR-XXX]*
*Deciders: [List of people involved in the decision]*

## Context

[Describe the issue motivating this decision. What is the problem we're facing? What constraints exist? What forces are at play?]

[Include relevant technical, business, and organizational context.]

## Decision

[State the decision that was made. Use active voice: "We will..." or "The system will..."]

[Be specific about what changes will be made and what approach will be taken.]

## Consequences

### Benefits

- [Positive outcome 1]
- [Positive outcome 2]
- [Positive outcome 3]

### Drawbacks

- [Negative outcome or trade-off 1]
- [Negative outcome or trade-off 2]

### Risks

| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| [Risk] | [Low/Med/High] | [Low/Med/High] | [How to address] |

## Alternatives Considered

### Alternative 1: [Name]

[Description of this alternative]

**Pros:**
- [Advantage]

**Cons:**
- [Disadvantage]

**Why rejected:** [Reason this wasn't chosen]

### Alternative 2: [Name]

[Description]

**Pros:**
- [Advantage]

**Cons:**
- [Disadvantage]

**Why rejected:** [Reason]

## Implementation Notes

[Any notes relevant to implementing this decision]

- [Implementation detail 1]
- [Implementation detail 2]

## References

- [Link to relevant documentation]
- [Link to discussion/RFC]
- [Link to related ADRs]

---

## Change Log

| Date | Author | Change |
|------|--------|--------|
| [Date] | [Name] | Initial draft |
```

---

## Quality Checklist

Apply this checklist before finalizing any ADR.

### Context

- [ ] Problem is clearly stated
- [ ] Constraints are documented
- [ ] Business and technical context included
- [ ] Scope is defined

### Decision

- [ ] Decision is explicitly stated
- [ ] Active voice used ("We will...")
- [ ] Specific about what changes
- [ ] Approach is clear

### Consequences

- [ ] Benefits are documented
- [ ] Drawbacks are honestly stated
- [ ] Risks are identified with mitigations
- [ ] Both short and long-term impacts considered

### Alternatives

- [ ] Multiple alternatives considered
- [ ] Each alternative fairly evaluated
- [ ] Rejection reasons are clear
- [ ] Pros and cons for each

### Metadata

- [ ] Status is current
- [ ] Date is accurate
- [ ] Deciders are listed
- [ ] ADR number is sequential

### ADR-Specific

- [ ] Appropriate for an ADR (not trivial)
- [ ] Self-contained and understandable
- [ ] Links to related ADRs if any
- [ ] Implementation notes if needed

### Maintainability

- [ ] References are linked
- [ ] Change log started
- [ ] Easy to update status later
- [ ] No broken links

### Formatting

- [ ] Consistent heading structure
- [ ] Tables properly formatted
- [ ] Lists are clear
- [ ] Readable and scannable