# Architecture Decision Records

## Purpose

Capture significant technical decisions so future contributors understand what was chosen, why it was chosen, and what tradeoffs were accepted.

## When to use

- A meaningful architectural or platform choice has been made
- Multiple alternatives were considered and context would otherwise be lost
- A decision will affect future implementation, migration, or team habits
- You want to prevent repeated re-litigation of the same tradeoff

## Inputs to gather

- The decision being made
- Alternatives considered
- Relevant constraints, drivers, and consequences
- Current status: proposed, accepted, superseded, or rejected

## How to work

- Record the decision close to when it is made.
- Keep the record concise but concrete enough to survive future context loss.
- Explain why the selected option won, not just what it is.
- Include consequences so future readers understand the cost of the choice.
- Update or supersede older records rather than leaving conflicting guidance unresolved.

## Output expectations

- A crisp decision record with context, choice, alternatives, and consequences
- Status that reflects whether the decision is still tentative or settled
- Links to implementation or follow-up docs when useful

## Quality checklist

- The decision is clear and specific.
- Alternatives and tradeoffs are visible.
- Future readers can understand the reasoning without redoing the whole discussion.
- The record stays short enough to remain useful.

## Handoff notes

- Reference the implementation, technical docs, or migration plan that operationalizes the decision.
- Pair with architecture and system design for major system changes.