Raw view: Write an architecture decision record
No invisible, zero-width, or bidi-control characters detected.
---
description: Write a numbered architecture decision record for a design choice
argument-hint: <decision topic, e.g. "use Postgres row-level security for tenant isolation">
allowed-tools: Read, Grep, Glob, Write, Bash(ls *), Bash(git log *)
---
Write an architecture decision record for: $ARGUMENTS
Existing ADRs:
!`ls docs/adr 2>/dev/null || ls doc/adr 2>/dev/null || ls docs/decisions 2>/dev/null || echo "(none)"`
Procedure:
1. Choose the directory: the existing one above, or `docs/adr/` if none. Number = highest existing number + 1, zero-padded to 4 digits. Filename: `NNNN-<kebab-title>.md`. If an existing ADR covers the same topic, read it and write this one as a superseding record that links back.
2. Ground the context in the repo: Grep for the components the decision touches, read the relevant config or module entry points, and cite file paths. Do not invent constraints; if a constraint is assumed, label it.
3. Consider at least two real alternatives besides the chosen one. For each: how it would work here, what it costs, what it blocks. A rejected option described in one dismissive sentence is a sign the analysis is incomplete.
4. Write the record in the template. Status is `Proposed` unless the user says it is decided.
5. Show the path and the Decision and Consequences sections in the reply.
Template:
# NNNN. <Title in the imperative, e.g. "Use Postgres RLS for tenant isolation">
Date: <YYYY-MM-DD>
Status: Proposed | Accepted | Deprecated | Superseded by [NNNN](NNNN-....md)
Deciders: <roles or names if given>
## Context
What situation forces a decision. Current state with file references. Constraints (performance, compliance, team, deadline) and which are hard.
## Options considered
### Option A - <name>
How it works here. Pros. Cons. What it makes hard later.
### Option B - <name>
...
### Option C - <name>
...
## Decision
Which option and the two or three reasons that decided it. What we are explicitly giving up.
## Consequences
- Positive: ...
- Negative: ...
- Follow-up work: <tickets or tasks this creates>
- How we will know it was wrong: <observable signal and the revisit trigger>
## References
- Related ADRs, issues, docs, benchmarks.