adr

Files (1)

• SKILL.md

SKILL.md (first lines)

# ADR

Architecture Decision Records preserve the reasoning behind decisions across
time and team turnover. The code shows what got built — an ADR shows why this
option won, what was ruled out, and what trade-offs were accepted on purpose.

## When to use

Trigger phrases: "create an ADR", "write this up as an ADR", "document this
decision", "ADR for this", "this is ADR-worthy".

Write an ADR when:

- A non-obvious architectural choice was made (technology, boundary, protocol,
  data model, deployment topology)
- A trade-off was accepted on purpose and a future reader would otherwise
  reverse it without context
- A constraint forced a non-default choice (compliance, performance budget,
  legacy compatibility)
- The conversation surfaced alternatives that were considered and rejected

Skip the ADR when:

- The choice is local and reversible (variable naming, formatter config,
  test layout)
- It's a TODO or aspiration, not a resolved decision
- The "decision" is just following the existing pattern in the codebase
- It's already documented in code comments where the constraint lives

## Process

### Step 1: Detect the repo's ADR convention

First, check for an `.adr-dir` file at the repo root (adr-tools convention) —
it points at the ADR directory. If present, use it.

Otherwise, check in this order for an existing ADR directory:

1. `docs/architecture/adr/`
2. `docs/decisions/` (MADR default)
3. `docs/adr/`
4. `adr/`
5. `doc/adr/`
6. `architecture/decisions/`
7. `decisions/`

If found:

- Read 1–2 existing ADRs to detect the template structure, frontmatter format,
  numbering pattern (`0001`, `ADR-001`, date-based), and slug style
  (`kebab-case`, `snake_case`)
- Look for a `template.md` in the same directory and reuse it verbatim if
  present
- Match the existing convention exactly — consistency beats opinion
- Skip subdirectories named `archived/`, `superseded/`, `examples/`, or
  prefixed `_` when computing the next number; only count files matching the
  detected naming pattern

**Repo convention vs mandatory visualization — precedence:** The repo's
template wins for section names and order. Insert the Mermaid block into the
closest equivalent decision/outcome section (or `Context` for before/after
diagrams). If the repo template explicitly disallows diagrams or has no
sensible place for one, write `No diagram: follows repo ADR template` in
place of the visualization.

If not found:

- Use the opinionated default: create `docs/adr/` and use the MADR-inspired
  fallback template below
- Numbering: `0001-` zero-padded 4-digit sequential
- Filename: `NNNN-imperative-kebab-case-title.md`

### Step 2: Confirm this is actually a decision

Before writing, verify the input qualifies:

- **Is it resolved?** "We should consider X" is a TODO, not an ADR. Push back
  if the conversation didn't reach a clear conclusion.
- **Is it architectural?** Variable names and lint rules don't get ADRs.
  Boundaries, protocols, technology choices, and trade-offs do.
- **Is there a meaningful "why"?** Capture at least one of: an alternative
  considered, a rejected baseline, or a forcing constraint (compliance,
  vendor, migration, safety, compatibility). A "constraint-forced
  non-choice" is one of the most valuable ADR types — explain *why* the
  apparently odd constraint was accepted, even if no realistic alternative
  survived. The status-quo "do nothing" option is a valid alternative if
  applicable.

If the input fails the "resolved" or "architectural" gates, tell the user
and don't write the ADR. If alternatives are absent, write the ADR with the
constraint that forced the call (and use "Only viable option because
\<constraint>" in Decision Outcome).

### Step 3: Gather inputs

**From the conversation, without re-asking:**

- The decision being made
- Alternatives that were discussed and rejected
- File paths, modules, or systems that were touched or referenced
- Constraints mentioned (deadlines, compliance, performance, compatibility)
- Tickets, prior ADRs, or external docs that came up

**Ask the user only for what's missing or unclear:**

- A clear imperative title ("Use Postgres for primary store" — not "Database
  decision")
- The final decision wording (the one-line outcome)
- The **negative** consequences and trade-offs — these are usually understated
  in chat and are the most valuable part of the ADR
- Status: usually "Proposed" unless the decision is already shipped, in which
  case "Accepted"

Don't fabricate alternatives that weren't actually considered. Don't invent
constraints that weren't mentioned. If a section would be guesswork, leave it
short and honest rather than padding it.

### Step 4: Add a visualization (default ON)

From clemens33/dotfiles, MIT.

More from clemens33/dotfiles