Architecture Decision Records

You are recording or retrieving an Architecture Decision Record (ADR) for this project. ADRs live in api/docs/arch/adr/ at the repo root.

When to record

Record these decisions:

• Technology selections (frameworks, libraries, databases, cloud providers)
• Architectural patterns (state management, caching strategy, API design)
• Data modeling choices (schema design, indexing, query approach)
• Infrastructure and deployment models
• Security, authentication, or testing strategy changes
• Any choice where the "why we didn't pick the alternative" will matter in 6 months

Skip: trivial choices (variable naming, formatting, minor refactors).

ADR template

Every ADR must have an H1 title stating the decision, and body prose covering the context, the decision itself, and the alternatives considered with why they were rejected. README.md and template.md are index/template files, not ADRs, and are exempt from this requirement.

The body may be short free-form prose covering those points, or the full template below (Date/Status/Deciders header block, Context, Decision, Alternatives Considered, Consequences). The full template is recommended for new ADRs but not required — the **Deciders**: line is always optional. If the decision, its context, or the rejected alternatives can't be stated, stop and ask the user for the missing information before writing the file.

# ADR-NNNN: [Decision Title]

**Date**: YYYY-MM-DD
**Status**: proposed | accepted | deprecated | superseded by ADR-NNNN
**Deciders**: [who was involved]

## Context

[2–5 sentences describing the situation, constraints, and forces at play]

## Decision

[1–3 sentences stating the change clearly and unambiguously]

## Alternatives Considered

### Alternative 1: [Name]

- **Pros**: [benefits]
- **Cons**: [drawbacks]
- **Why not**: [specific rejection reason]

### Alternative 2: [Name]

- **Pros**: [benefits]
- **Cons**: [drawbacks]
- **Why not**: [specific rejection reason]

## Consequences

### Positive

- [benefit 1]

### Negative

- [trade-off 1]

### Risks

- [risk and mitigation]

Workflow — recording a new ADR

1. Scan existing ADRs — Glob api/docs/arch/adr/[0-9]*.md to find the highest existing number.
2. Assign next ID — next sequential 4-digit number (e.g., 0003).
3. Gather context — ask the user for any missing details on the context, the decision, and the alternatives considered with why they were rejected. Only ask about deciders and consequences if the user opts into the full template.
4. Draft the ADR — cover the context, decision, and rejected alternatives, either as free-form prose or using the full template above.
5. Present the draft — show it to the user for review before writing any file.
6. Write the file — api/docs/arch/adr/NNNN-kebab-title.md (kebab-case title, all lowercase).
7. Update the index — append a new row to the | ADR | Title | Status | Date | table in api/docs/arch/adr/README.md.

Workflow — reading / querying ADRs

1. Check if api/docs/arch/adr/README.md exists. If not, offer to start the ADR directory.
2. Read the README index table and find entries relevant to the user's question.
3. Read the matching ADR file and summarise the Context and Decision sections.
4. If no ADR matches, suggest recording one now.

Quality standards

• Each ADR should be readable in under 2 minutes.
• Every rejected alternative must include a Why not reason — "we didn't pick X" without a reason is useless.
• When a decision is superseded, update the old ADR's Status field to superseded by ADR-NNNN and create the new ADR with a back-reference in its Context.
• Keep one decision per ADR — split if two separate choices are getting conflated.