Adr Writer

---
name: adr-writer
description: Write an Architecture Decision Record for a significant technical choice — context, the decision itself, alternatives genuinely considered, consequences (good and bad), operational impact, a rollback/reversal plan, and a review date. Use when a decision has just been made and needs durable recording, when asked to "write an ADR" or "document why we chose X", or when architecture-designer hands over an ADR draft for completion. Also use to record a rejected option or a superseded decision. Do NOT use for a full design doc (tech-spec-writer) or curating the ADR log — numbering, status, supersede links (adr-sequencer), or to MAKE the decision — open design questions go to architecture-designer; contested facts go to source-of-truth-reconciler first.
---

# ADR Writer

## Purpose

Produce an Architecture Decision Record (ADR) — a short record of one
significant technical decision — that lets a future reader, including a
future agent, understand why the system is the way it is, what was rejected and
why, what it costs to operate, and exactly how to back out if the decision's
assumptions fail. The rollback/reversal plan and the review date are
mandatory: a decision with no reversal path is a bet, and one with no review
date silently becomes permanent.

## Use When

- Use when: a significant technical decision was just made or a specific
  option was formally proposed for decision and needs a clearly proposed
  record — framework choice, boundary placement,
  datastore, build-vs-buy, deprecation. The five status values are defined at
  Workflow step 8.
- Use when: `architecture-designer` hands over an ADR draft to complete.
- Use when: an old decision is being superseded or reversed — that gets its
  own ADR linking both directions.
- Do NOT use when: the decision has not actually been made and options are
  genuinely open — that is `architecture-designer` (or a human conversation).
- A rejected option can be recorded under **Alternatives Considered**; it is
  not automatically a rejected ADR. When the repository has an ADR corpus,
  hand numbering, lifecycle status, index and bidirectional links to
  `adr-sequencer`.
- Do NOT use when: sources disagree about what was decided — run
  `source-of-truth-reconciler` first; an ADR must not launder a contested
  claim into official history.
- Do NOT use when: the artifact is a full design doc covering a whole
  change — that is `tech-spec-writer` (which may embed several ADRs); this
  skill records one decision.
- Do NOT use for trivial choices with no architectural consequence — an ADR
  per linting rule buries the decisions that matter.

## Inputs to Inspect

1. The decision statement from the human or the `architecture-designer`
   draft — exactly what was decided, by whom, when.
2. Existing ADRs: numbering scheme, directory (`docs/adr/` or repo
   convention), status vocabulary, and any ADR this one supersedes.
3. The code/config areas the decision touches — enough to describe
   operational impact concretely.
4. The alternatives that were actually on the table, with the real reasons
   they lost (ask if not stated; do not invent).

## Workflow

Draft in the conversation first. Persist an ordinary non-executable ADR only
under the approved-documentation exception in the
[skill-generation standard](../../../docs/skill-generation-standard.md#5-least-privilege--side-effects):
show exact path/content,
honor an applicable existing current-session grant or obtain missing approval,
create/append without overwriting history, then verify the write. Security or
governance policy, agent instructions and existing-file amendments/backlinks require
their separately authorized manual route; this automatic drafting phase does
not execute those changes or broaden a grant.

1. **Locate the ADR home and number.** Follow the repo's existing convention;
   propose `docs/adr/NNNN-title.md` naming only if no convention exists.
2. **State the context:** the forces, constraints, and the problem as it
   stood at decision time — written so it stays true even after the code
   changes. No solution language in the context section.
3. **State the decision** in one or two sentences, active voice ("We will…").
4. **Record alternatives** genuinely considered, each with the actual reason
   it was rejected. "Considered nothing" is a finding to raise, not a section
   to skip.
5. **Record consequences — both signs.** What gets easier, what gets harder,
   what new obligations appear (upgrades, licenses, training, coupling).
6. **Describe operational impact:** deployment, monitoring, on-call surface,
   failure modes, cost profile.
7. **Write the rollback/reversal plan:** the concrete conditions that would
   trigger reversal, the steps to back out, what data or contracts make
   reversal hard, and the point of no return if one exists. "N/A" is not
   acceptable; "reversal is impractical after X because Y" is.
8. **Set status and review date:** use the repository's lifecycle vocabulary —
   proposed (drafted, awaiting a decision), accepted (the current decision),
   rejected (considered and declined, kept as history), deprecated (no longer
   recommended, no direct replacement) or superseded (replaced by a specific
   newer ADR, where supported) — and a specific date to re-examine the
   decision against its assumptions.
   Include predecessor links in the draft; propose any old-file back-link
   change for its separately authorized route rather than editing it here.
   Label the status, and every claim the decision depends on, with one
   certainty level: confirmed (backed by cited evidence), inferred (reasoned
   from evidence but not shown directly) or unknown — for example,
   `accepted (confirmed)`. Write an uncited operational claim as "unverified —
   recommend confirming", never as fact. The ADR index that lists every
   record's status belongs to `adr-sequencer`.
9. **Cross-check:** could a new team member reconstruct the decision's logic
   from this document alone, without hallway context?

## Output Format

A Markdown draft and exact target following [assets/adr-template.md](assets/adr-template.md);
report separately whether authorized persistence actually occurred:

```
# ADR-NNNN: <title, imperative>
Status: proposed | accepted | rejected | deprecated | superseded by ADR-MMMM
        (confirmed | inferred | unknown)
Date: <decision date>   Review by: <specific date>
## Context          <forces and problem, solution-free>
## Decision         <"We will …">
## Alternatives Considered   <option — why rejected>
## Consequences     <positive / negative / new obligations>
## Operational Impact        <deploy, observe, on-call, cost>
## Rollback / Reversal Plan  <trigger conditions, steps, hard parts,
                              point of no return>
```

## Validation Checklist

- [ ] Numbering, location, and status vocabulary match existing repo ADRs.
- [ ] Context section contains no solution language.
- [ ] Every alternative has the real rejection reason, not a strawman.
- [ ] Consequences include at least one genuine negative.
- [ ] Rollback plan has trigger conditions AND steps; impractical reversal is
      explained, never blank.
- [ ] Review date is a specific date, not "later".
- [ ] Status and load-bearing claims carry a certainty label; no uncited
      operational claim is stated as confirmed.
- [ ] The draft links to its predecessor and proposes the reverse link; old-file changes require separate application evidence.

## Gotchas

- ADRs written weeks later reconstruct a tidier story than reality; record
  the messy real reasons — they are the useful ones.
- The most common defect is a consequences section with only upsides; if no
  downside is listed, the alternatives were not taken seriously.
- A rollback plan that says "revert the commit" ignores data written, contracts
  published, and consumers migrated in the meantime — walk the actual state.
- Decision-by-momentum ("we already started using it") is a context fact worth
  recording honestly; hiding it makes the ADR read as more deliberate than it was.
- Do not renumber or rewrite historical ADRs to match new conventions;
  supersede them.

## Stop Conditions

- The "decision" turns out to be contested or unmade → stop; route to
  `architecture-designer` or the human. An ADR must record, not decide.
- Sources disagree on what was decided or why → `source-of-truth-reconciler`
  first.
- The decision crosses a security/data/tenant boundary that was never
  approved → flag via `human-approval-boundary` before recording it as
  accepted.
- No alternatives can be named even after asking → record status "proposed"
  and raise the gap; do not fabricate a comparison.

## Supporting Files

- [assets/adr-template.md](assets/adr-template.md) — the full ADR file
  template with section-by-section guidance comments.
- `evals/evals.json` — trigger + behavior cases.
- `evals/trigger-evals.json` — discrimination against `domain-modeler` and
  `architecture-designer` (design cluster).