---
description: Record an architecture decision as a correctly templated, numbered, and indexed ADR in one invocation. Use unprompted WHEN a decision of real consequence has just been made or is being made mid-task — choosing between technologies, setting a convention, changing an approach the codebase already uses, or reversing/superseding a previously recorded decision (a reversal is itself a decision that must be recorded). Invoked by `/os-adr:create`.
---

Create a new ADR under `docs/adr/`. All mechanical work (ID assignment, templating, index
regeneration, supersession bookkeeping) is done by the plugin's CLI — never hand-author the
file, number, or index.

**Moments that warrant an ADR** (recognize these unprompted; don't wait to be asked):

- a technology/library/protocol choice with alternatives that were genuinely considered
- a convention or pattern the codebase will now follow
- a change that replaces an approach the codebase already uses
- a **reversal of an existing Accepted ADR** — a task that reverses a recorded decision is
  **not complete** until the superseding ADR is created (`supersedes: NNNN`); implementing
  the change and stopping leaves the ADR history asserting the opposite of what the code does

## 1. Gather the decision content

From the conversation (ask only for what you cannot infer):

- **title** — short, imperative or noun-phrase ("Use Postgres for persistence")
- **context** — the forces/problem that made a decision necessary
- **decision** — what was decided, stated actively
- **consequences** — what becomes easier/harder as a result
- **alternatives** — options considered and *why each was rejected* (highest-value field; push
  for real reasons, not placeholders)
- **affected_paths** / **affected_components** — repo paths and component names this decision
  governs (used for deterministic retrieval later; be concrete, e.g. `["src/db/", "config/database.yml"]`)
- **status** — default `Accepted`; use `Proposed` only if the user says it isn't settled
- **supersedes** — 4-digit ID, only if this replaces an existing ADR (check `docs/adr/README.md`)

If the project has no `docs/adr/` yet, run `/os-adr:init` first (or its CLI, step 2's
`adr-init`).

## 2. Invoke the CLI

```bash
echo '{"title": "...", "context": "...", "decision": "...", "consequences": "...",
  "alternatives": "...", "affected_paths": ["..."], "affected_components": ["..."]}' \
  | ruby ${CLAUDE_PLUGIN_ROOT}/bin/adr-new --root <project-root>
```

Optional JSON fields: `status`, `date` (ISO), `supersedes` ("NNNN"). The CLI prints the created
file path, sets `superseded-by` + `Superseded` status on any superseded ADR, and regenerates
`docs/adr/README.md`. Prefer writing the JSON to a temp file and piping it (`cat file | ...`)
when section bodies contain quotes.

## 3. Confirm

Show the user the created path and a one-line summary. Do not edit the generated index by hand.