---
description: Write a numbered Architecture Decision Record for a technical decision
argument-hint: <decision and context>
allowed-tools:
  - Read
  - Grep
  - Glob
  - Write
  - Edit
  - Bash(ls *)
  - Bash(git log *)
---

Decision input: $ARGUMENTS

If empty, ask what was decided and why, and stop.

## 1. Locate

- Look for an existing ADR folder: `docs/adr`, `docs/decisions`, `docs/architecture/decisions`, `adr`, `doc/adr`. If none, use `docs/adr/`.
- List existing files. Next number = highest existing number + 1, zero-padded to the same width (default 4 digits).
- If existing ADRs exist, read two of them and match their headings, status values and tone.

## 2. Gather evidence

- Identify the code areas the decision affects. Search for the relevant modules, config files, dependencies and infrastructure files. Note paths.
- Check whether an earlier ADR covers the same topic. If this one replaces it, note that.

## 3. Ask what you cannot find

Ask the user, in one message, only for missing items among:
- The problem or forcing event.
- Constraints (budget, deadlines, compliance, team skills).
- Alternatives that were considered and why each was rejected.
- Status: Proposed (default) or Accepted, and who decided.

If the user says to proceed without answers, write "Not recorded" for those parts. Do not invent them.

## 4. Write

File: `<folder>/<NNNN>-<kebab-case-title>.md`

```
# <NNNN>. <Decision as a short imperative phrase>

- Status: Proposed | Accepted | Superseded by [ADR-XXXX](XXXX-....md)
- Date: <YYYY-MM-DD>
- Deciders: <names or "Not recorded">

## Context
<the forces at play: problem, constraints, current state with code references like `src/queue/worker.ts`>

## Decision
<what we will do, stated plainly, in active voice: "We will ...">

## Alternatives considered
### <Option>
<summary; why not chosen>

## Consequences
Positive:
- ...
Negative and risks:
- ...
Follow-up work:
- ...
```

## 5. Supersede

If this ADR replaces an earlier one, edit the earlier ADR's status to `Superseded by [ADR-<NNNN>](<file>)` and add `Supersedes [ADR-XXXX](<file>)` under this ADR's status line. Change nothing else in the old ADR.

## 6. Finish

Print the path of the new file and the questions that were answered "Not recorded".