| name | adr-writer |
| description | Use when a hard-to-reverse architectural decision is made — during plan-writer, a refactor, a doubt-driven trade-off, or a handoff PAUSE — to write it as an immutable ADR in docs/architecture/adr/ from the ADR template, or to supersede an existing one. |
adr-writer
When: a decision that is hard to reverse has been made (or is about to be). ADRs are durable; docs/STATE.md is volatile. Never let a structural decision live only in STATE, a commit message, or the chat.
Template: docs/architecture/adr/_template.md.
Output: docs/architecture/adr/NNNN-kebab-case-title.md.
Does this deserve an ADR?
Write one when the decision is hard to reverse AND has consequences beyond the current feature:
- Dependency direction, layer or module boundary, aggregate boundary.
- Adopting/replacing a framework, database, protocol, or external service.
- Persistence model or public contract shape (API, event, schema).
- Deliberately accepting a trade-off or technical debt.
Skip it for reversible or local choices (a variable name, a helper's location, a one-file refactor). Those belong in the code and, if in flight, in STATE. When unsure, ask the user rather than growing the ADR log with noise.
Steps
- Determine the number:
NNNN = highest existing ADR in docs/architecture/adr/ + 1, zero-padded to 4 digits, sequential and never reused. _template.md and index.md are not ADRs.
- Copy
_template.md and fill every section against what was actually decided:
- Context — the problem, the forces, the constraints, why this must be decided now.
- Decision — present tense ("We will use X because…"). One decision per ADR.
- Alternatives Considered — real options that were weighed, each with why it lost. An ADR with no alternatives is a note, not a decision.
- Consequences — positive, negative/trade-offs, and neutral. Naming the negative consequence is the point; an ADR with only upsides is not honest.
- Status —
proposed while the user has not agreed; accepted once they have.
- Decision makers and Date (today's date,
YYYY-MM-DD).
- Ground it in evidence: cite the spec/plan, the constitution rule, or the code that forced the decision. Do not invent a rationale after the fact — if the real reason was a constraint or a deadline, write that.
- Register it as an OKF concept: the frontmatter carries
type: adr, title, and a one-sentence description, so the SessionStart okf-index hook surfaces it. Cross-link related concepts with relative markdown links ([Title](../../design-notes/XXXX.md)), and link back from the spec/plan that motivated it.
- Refresh the knowledge index —
node .specify/gates/okf-build-index.mjs build docs — otherwise the freshness gate blocks the commit.
- Report the ADR path and its status to the user. Do not commit; ADRs ride with the feature's commit, proposed and approved like any other change.
Changing a decision: supersede, never edit
ADRs are append-only. An accepted ADR is a historical record of what was decided and why, at that time — editing it destroys the reasoning trail that makes it worth keeping.
To change a decision:
- Write a NEW ADR with the next number. Its
Context states what changed since the old one (new constraint, new evidence, the trade-off went bad).
- Edit the OLD ADR's
Status line only: superseded by ADR-XXXX. Touch nothing else in it.
- Link the two in both directions.
The single exception: an ADR still in proposed status has not been agreed to yet, so it may be edited freely until it becomes accepted.
Fixing a typo or a broken link is not "changing a decision" — that is fine.
Rules
- One decision per ADR. Two decisions = two ADRs, even if made in the same conversation.
- Never edit an accepted ADR except its Status line when superseding.
- Never renumber, reuse, or delete an ADR number — a superseded ADR stays in the tree.
- Never invent consequences. If a consequence is unknown, say it is unknown.
- Never commit on your own; propose and wait, per the project's commit-at-milestone rule.
Related
handoff — writes the volatile STATE; delegates durable decisions here.architecture — the agnostic principles behind most decisions worth recording.plan-writer — the phase where boundary/dependency decisions usually surface.doubt-driven-development — a legitimate trade-off found there gets recorded as an ADR.
