adr

ADR

Record a concrete architectural decision in a format optimized for future readers — typically the team member six months from now wondering "why did we do it this way?"

ADRs are not exploratory. If the user is still weighing options, redirect to /rfc. ADRs assume the decision is made (or being made in this moment) and the job is to capture context + reasoning before they decay.

Steps

1. Confirm the decision is actually settled. If the user describes multiple options without picking one, say so and suggest /rfc instead.
2. Find the repo's ADR location. Check docs/adr/, docs/decisions/, adr/, .adr/. Mirror existing numbering and naming (0042-use-postgres-jsonb-for-events.md style). If none exists, propose docs/adr/0001-<slug>.md and let the user confirm.
3. Look for an ADR template in the repo (docs/adr/template.md, adr-template.md). If present, follow it exactly. Otherwise use the structure below.
4. Date the ADR. Use today's date in YYYY-MM-DD.
5. Status starts as "Accepted" unless the user is recording a historical decision now superseded (then Superseded by ADR-NNNN) or one still in review (Proposed).

Default structure (when no repo template exists)

# ADR-NNNN: <Short decision title>

- **Status:** Accepted
- **Date:** YYYY-MM-DD
- **Deciders:** <names or roles>

## Context

What forces are at play? What's the problem and constraints? Keep it to what's
needed to understand the decision — not the full history of the project.

## Decision

We will <action verb> <thing>. State the choice plainly. One paragraph max.

## Consequences

### Positive
- ...

### Negative
- ...

### Neutral
- What changes operationally / for new contributors / for adjacent systems.

## Alternatives Considered

Brief — one or two sentences each. Why each was rejected. This is not an RFC;
do not re-litigate the full trade-off table.

## References

- Linked RFC, PR, ticket, prior ADR, external doc.

Rules

• One decision per ADR. If the user is describing two decisions, write two ADRs.
• Don't invent Deciders. Infer from git config, PR author, or commit author. If you can't determine them, write <TBD> and ask the user — never fabricate names or roles.
• No marketing prose. "We have decided to leverage the strategic synergies of..." — no. "We will use Postgres jsonb instead of a separate events table because..." — yes.
• Past-tense context, present-tense decision, future-tense consequences. ("X was painful because... → We will use Y → New contributors will need to...")
• Immutable after acceptance. If the decision changes, write a new ADR that supersedes this one. Do not silently edit history. Mention this rule to the user when they ask to "update" an accepted ADR.