adr-new

# /adr-new

## What it does

Creates a new numbered ADR file in `docs/adr/` and adds an entry to the
index. ADRs are the lightweight memory of *why* the architecture looks
the way it does — without them, six months from now nobody (human or
agent) remembers why we chose A instead of B.

The convention is documented in
[`docs/adr/README.md`](../../docs/adr/README.md): MADR-flavored,
numbered, immutable status (proposed → accepted → deprecated /
superseded).

## Workflow

1. **Find target dir.** Default `docs/adr/` from the current repo root
   (via `git rev-parse --show-toplevel`). If no `docs/adr/` exists,
   ask the user: "create it now?". If yes, also copy
   `templates/adr-template.md` if shipped (the plugin ships its own
   template under `docs/adr/template.md` — useful as a reference even
   when the target repo doesn't have one yet).

2. **Pick next number.** List existing `docs/adr/NNNN-*.md` files,
   parse the leading number, take the max + 1. Pad to 4 digits.

3. **Get the title.**
   - If `$ARGUMENTS` has a positional, use it as the title.
   - If `--noninteractive`, fail if no title was given (we won't
     hallucinate one).
   - Otherwise, prompt the user.
   - Convert to kebab-case for the filename:
     `0042-replace-polling-with-webhooks.md`.

4. **Ask for context** (skip in `--noninteractive`):
   - One-line summary of the problem.
   - The chosen option (one sentence, stated as fact in present
     tense).
   - 1–3 alternatives considered (one line each).
   - Whether to mark `status: proposed` (default) or `accepted` (if
     the team already decided in conversation and just needs the
     record).

5. **Generate the file** at `docs/adr/<NNNN>-<kebab-title>.md` using
   the MADR template (the plugin ships
   [`docs/adr/template.md`](../../docs/adr/template.md) for reference).
   Substitute:
   - `NNNN` → resolved number
   - `Title` → user-provided title
   - `YYYY-MM-DD` → today (`date +%Y-%m-%d`)
   - `Status` → resolved value
   - Context / Decision / Alternatives → user input or
     `<TODO: fill in>` placeholders if user skipped them

6. **Update the index.** Append the new ADR to the bulleted list in
   `docs/adr/README.md` (or create it if it doesn't exist). Preserve
   the existing index style:
   `- [NNNN — Title](NNNN-kebab.md)`

7. **Report.** Print the new file path and remind the user that ADRs
   are immutable once `accepted` — future revisions are *new* ADRs
   superseding the old one, not edits.

## Hard rules

- **Numbers are immutable.** Once shipped, an ADR's number never
  changes. If you regenerate the file (because of typos in the title
  before commit), keep the number.
- **Status is immutable once `accepted`.** Edits to an `accepted` ADR
  should be limited to typos and link fixes. Substantive changes ship
  as a new ADR that explicitly supersedes the old one
  (`Status: superseded by NNNN`).
- **The index is the source of truth for "what ADRs exist."** Always
  update it; never let it drift from the directory contents.
- **Never overwrite an existing ADR.** If the kebab-title collides
  with an existing file, ask the user for a different title.

## Tunables

- `--status accepted` — start the ADR as `accepted` rather than
  `proposed`. Use when the decision is already settled and you're just
  recording it.
- `--noninteractive` — skip prompts; requires a title positional and
  fills the context/decision/alternatives with `<TODO>` placeholders.
- `--dry-run` — print what would be written, write nothing.

## When to write an ADR (and when not to)

**Write an ADR for:**
- Architectural tradeoffs likely to be re-litigated (e.g., "no
  embedding RAG", "AGENTS.md canonical, CLAUDE.md import").
- Decisions that depend on external constraints (a vendor, an open
  issue, a benchmark result).
- Decisions where alternatives are plausible enough that a future
  agent will propose them.

**Don't write an ADR for:**
- Implementation choices the code itself shows (variable names,
  function structure).
- One-off tactical fixes.
- Things covered by an obvious convention (test naming, lint config).

If you're not sure: write it. Three sentences in `docs/adr/0042.md`
is cheap; re-arguing the same point six months later is expensive.

## What this skill does NOT do

- **Doesn't make the decision.** It records a decision you've already
  made. If you don't yet know the decision, you want a `docs/specs/`
  document (or `superpowers:brainstorming`), not an ADR.
- **Doesn't read the conversation context.** You tell it the
  decision in your own words; the skill just structures the file.
- **Doesn't supersede or modify existing ADRs.** Modification is a
  manual edit + new ADR with `Status: superseded by NNNN`.