Arsenalist/adr.md

## adr.md

      
    Raw
  

              adr.md
            
          
    description
    Create or supersede an Architecture Decision Record under site/internal/src/content/docs/adrs/
  
  
    argument-hint
    
  
  short title — optional
  
  
Create / supersede an Architecture Decision Record

Use this command when documenting an architectural decision made during a task. ADRs live in the Starlight internal docs site under site/internal/src/content/docs/adrs/ (URL: /internal/docs/adrs/).
Inspired by adr-tools (Nygard format), adapted for Starlight's frontmatter and Amplify's repo layout.
When to use this

Create an ADR when your work involves any of these:

Choosing a storage strategy (e.g., where some state lives — DB column vs Postgres jsonb vs Oban arg vs S3)
Adding or removing a major dependency (mix.exs, npm package, system service)
Introducing or removing a core abstraction (new context module, new CQRS aggregate, new behaviour)
A cross-cutting decision that future code should follow (locale isolation, error code shape, etc.)
A decision that overrides or replaces an earlier ADR

Do NOT create ADRs for: bug fixes, UI styling, behavior-preserving refactors, test-only changes, or copy edits.
If you are unsure → create one. A throwaway ADR is cheaper than a lost rationale.

Creating a new ADR

1. Find the next ID

Run this from the repo root:
ls site/internal/src/content/docs/adrs/*.md 2>/dev/null \
  | grep -oE '/[0-9]{4}-' \
  | grep -oE '[0-9]{4}' \
  | sort -n \
  | tail -1 \
  | awk '{printf "%04d\n", $1+1}'
If no numbered files exist yet, start at 0001.
2. Create the file

Filename: site/internal/src/content/docs/adrs/NNNN-short-kebab-title.md
Template:
---
title: "ADR-NNNN: Short decision title"
description: One-sentence summary of the decision (shown in search / link previews)
adr_id: "NNNN"
status: active
date: "YYYY-MM-DD"
tags:
  - <area>          # e.g., persistence, payments, auth, cqrs, frontend, i18n
  - <area>
# supersedes: "000M"        # uncomment if this ADR replaces another
# superseded_by: "NNNN"     # set later if/when this ADR is replaced
---

## Context

The issue motivating this decision, and any context that influences or constrains it. Answer "why now?" — what forced the question to be made today.

## Decision

**The change we're proposing or have agreed to implement.** State it clearly in one or two sentences — bold so it stands out.

## Options considered

- **Option A** (chosen): brief description — pros / cons
- **Option B**: brief description — pros / cons
- **Option C**: brief description — pros / cons

## Consequences

What becomes easier or harder as a result?
What risks does this introduce that will need to be mitigated?
What would trigger re-evaluation of this decision?

## Advice

*(optional)* Input received before making this decision — who was consulted, what they said. Omit this section if the decision was made without external input.
Required frontmatter fields:

title — Starlight uses this as the page title and sidebar label. Prefix with ADR-NNNN: so the sidebar reads as an index.
description — used by Starlight for search + meta tags.
adr_id — the four-digit string (matches the filename).
status — proposed, active, superseded, or deprecated.
date — today's date, YYYY-MM-DD.
tags — array of classification tags. Used by the index table for grouping.

3. Update the index

Edit site/internal/src/content/docs/adrs/index.md. Add a row to the active table (keep it sorted by ID descending — newest first):
| [NNNN](./NNNN-short-kebab-title) | Short decision title | active | YYYY-MM-DD | area, area |
If you superseded a prior ADR (see below), also move its index row from the active section to the superseded section.
4. Fold the ADR into the feature commit

git add site/internal/src/content/docs/adrs/NNNN-*.md \
        site/internal/src/content/docs/adrs/index.md
# stage the ADR alongside the feature change — do not create a separate ADR-only commit
The ADR is part of the change; reviewers should see the decision and the code together.

Superseding an existing ADR

Equivalent of adr new -s <N> from adr-tools — do this in three steps:
Step 1: Mark the old ADR as superseded

Edit the existing file. Update only the frontmatter:
---
title: "ADR-000M: Old decision title"
...
status: superseded          # ← change from active
superseded_by: "NNNN"       # ← add this
---
Never edit the content sections of an active ADR — once committed, content is immutable. Only status metadata changes.
Step 2: Create the new ADR

Follow the steps above. In the supersedes frontmatter field and in the Context section, reference the older ADR:
supersedes: "000M"
## Context

Supersedes [ADR-000M](./000M-old-title). [explain why the old decision no longer holds]
Step 3: Update the index

In site/internal/src/content/docs/adrs/index.md:

Move the old row from the Active table to the Superseded table (update its status column).
Add the new row to the Active table.


Best practices (from adr-tools / Nygard)


One decision per ADR. If you find yourself writing "and also", split it.
Write Decision first. If you can't state it in 1–2 sentences, the decision is too vague.
Context is the "why now." What forced this decision to be made today?
Consequences must include negatives. A one-sided ADR is a red flag.
Committed = immutable. Once pushed, body content doesn't change; only status metadata does.
If in doubt, create one. Cheaper to have an unnecessary ADR than to lose context.


How this command interacts with other surfaces


Skill adr — auto-suggests this command when the conversation contains architectural-decision language. It uses the same template.
Stop hook (.claude/hooks/adr-stop.sh) — at end-of-turn, nudges if architectural keywords appeared and no ADR was created. Opt out by replying skip adr or no adr in the session before stopping.
No results found