adr-manager

# ADR Manager

## Overview

This skill appends Architecture Decision Record entries to an ADR file. ADRs capture significant architectural decisions, providing future maintainers with context about why decisions were made.

Based on [Michael Nygard's ADR template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).

## Adding an ADR Entry

Read the existing ADR file to determine the next sequential number, then append a new entry.

ALWAYS include a context link: `**Build:** [bld-<project-slug>](./.artifacts/bld-<project-slug>/)`

### Entry Format

```markdown
## ADR-<NNN>: <Title>

<context-link>

### Status

<status>

### Context

<context>

### Decision

<decision>

### Consequences

<consequences>

---
```

### Field Guidance

- **ADR-NNN**: Sequential number (ADR-001, ADR-002, etc.). Read existing entries to determine next number.
- **Title**: Concise description of the decision (e.g., "Use PostgreSQL for persistence", "Adopt event-driven architecture")
- **Context link**: If provided by caller, include as `**Build:** [link](./path/)` or similar. Omit if not provided.
- **Status**: One of `proposed`, `accepted`, `rejected`, `deprecated`, `superseded`
- **Context**: The issue or situation motivating this decision. What forces are at play?
- **Decision**: What was decided and why. Be specific about the choice made.
- **Consequences**: What becomes easier or harder as a result. Include both positive and negative impacts.

### When to Add an Entry

Add an ADR entry when:
- Choosing between competing technologies or frameworks
- Selecting significant architectural patterns
- Making trade-offs with meaningful consequences
- Deviating from the original plan
- Making decisions that future maintainers would benefit from understanding

Do NOT add entries for:
- Routine implementation details
- Minor code organization choices
- Decisions that are easily reversible with no significant impact

### Example Scenarios

✅ **Add ADR:** "Chose Next.js App Router over Pages Router for better streaming support"
✅ **Add ADR:** "Adopted Zustand for state management due to simplicity vs Redux complexity"
✅ **Add ADR:** "Implemented optimistic UI updates to improve perceived performance despite network latency"
✅ **Add ADR:** "Selected PostgreSQL over MongoDB for ACID guarantees in financial transactions"

❌ **Skip ADR:** Used standard file structure conventions
❌ **Skip ADR:** Followed existing error handling patterns
❌ **Skip ADR:** Wrote unit tests using the project's existing test framework
❌ **Skip ADR:** Applied consistent naming conventions across components

### Quality Guidelines

- Keep entries concise — capture the "why" for future reference, not exhaustive documentation
- Focus on decisions with lasting impact
- Be honest about trade-offs and consequences
- Write for someone encountering this codebase months or years later