Reference — generated from the toolkit

Source of truth: toolkit/skills/adr-writing/spec.md. Edit it there; this page is regenerated on build.

Skill: adr-writing

• Owner: AI + Engineering
• Version: 0.1.0
• Lifecycle: draft
• Phase: build

Trigger

Work in progress implies a decision that is costly to reverse or easy to forget the reason for — the threshold in the decision-records standard. Invoked when an agent's build work surfaces such a decision, or when a human asks for a decision context to be written up. The merge gate checks that flagged change types carry an ADR, so this skill is what keeps that check cheap to satisfy honestly.

Inputs → outputs

• Inputs: the decision context — problem, constraints (technical, domain, regulatory, commercial), the options actually considered with their trade-offs, and the direction chosen or proposed — plus the target repo's existing docs/adr/ directory.
• Outputs: a draft ADR per the ADR template, named NNNN-kebab-title.md with the next zero-padded number, Status always Proposed — a human accepts, never the skill — with links to any related ADRs it may supersede and a revisit-by date or trigger proposed.

Procedure

1. Read the existing ADR directory; identify related decisions and any accepted ADR the new decision would conflict with or supersede.
2. Draft the Context section as forces and facts — constraints, not conclusions.
3. Record the options actually considered, each with its trade-offs. Options not genuinely evaluated are not padded in to look thorough.
4. State the decision plainly with the decisive reasons, then the consequences: positive, negative/accepted cost, and follow-ups (including radar moves for toolkit-type decisions).
5. Where the decision supersedes an existing ADR, add the Superseded by cross-links to the draft — proposed in the new file, with the edit to the old ADR's status prepared for the human who accepts.
6. Propose a revisit-by date or trigger condition; assign the next sequential number; attach the draft to the PR it justifies.

Guardrails & permissions

• Status is always Proposed — the skill never marks an ADR Accepted, and acceptance authority follows the RACI.
• Never edits an existing ADR's decision content — history is superseded, not rewritten. The only prepared change to an old ADR is its status line, applied by the accepting human.
• One decision per file; below-threshold decisions are declined with a one-line note rather than recorded as noise.
• Standard agent guardrails; writes only within the target repo's decision-record directory and the open PR.

Failure modes

• Recording trivia — ADR inflation that buries the decisions that matter (mitigated: the standard's threshold test applied before drafting; declined drafts are logged as one-liners).
• Missing an existing conflicting ADR (detected: directory scan in step 1 plus reviewer check; an agent later "happily undoing" a decision is exactly the failure ADRs exist to stop).
• Post-hoc rationalisation — inventing options that were never considered (mitigated: options come from the supplied context only; reviewers reject padded options).
• Vague revisit triggers (mitigated: a date or a concrete condition is required; "when appropriate" fails the draft).

Golden scenarios

Scenario	Input	Expected output	Pass criterion
Standard decision context	fixture context (queue vs cron for MTA batch)	complete ADR, status Proposed, next number, revisit trigger	all template sections present; status check
Supersede case	context conflicting with fixture ADR-0003	draft links ADR-0003 as superseded; old file untouched	cross-links proposed; zero edits to existing ADRs
Below-threshold decision	trivial, easily-reversed choice	declined with one-line note, no ADR file	no file created; note emitted