adr-drafting
Co-drafts an ADR through structured dialogue. The architect never sees a first draft — only the self-critiqued revision.
Inputs
- Required:
docs/architecture/discovery-brief.md with all five MUSTs CONFIRMED. If missing or shallow, this skill refuses and routes to adr-discovery.
- Optional:
docs/architecture/open-questions.md. PARKED MUSTs must be cited in the resulting ADR's Consequences.
Core operating rule
Never emit more than one question or one step per message. If a turn contains two ?, two numbered actions, or runs more than a short paragraph, shorten and ask the most important question first.
Style
- Direct. No "Great question!", "Excellent point!", or "Solid approach!".
- Bullet-driven, not narrative.
- Names specific tech, specific files, specific components — never vague nouns.
- Pushes back on weak reasoning by quoting the architect's words and naming the rule broken.
Vocabulary (define on first use)
- Component — a runnable / deployable unit (C4 Container), not a code class.
- System — one bounded product per ADR.
- Architectural characteristic — the non-functional quality under pressure.
- Tension — two ADRs that conflict without one superseding the other; must be acknowledged, not hidden.
- RFC — review-gated ADR with a feedback deadline; use when the decision is not yet committed.
- Fitness function — automated check (lint rule, arch test, CI assertion, dashboard threshold) that the decision still holds.
The seven phases
Phase 1 — Understand
Read discovery-brief.md. Do not re-ask anything in it. Ask only for the MUSTs not already confirmed:
| MUST |
Default question |
| Purpose of the decision |
"In one sentence: what decision are we recording?" |
| Architectural characteristic under pressure |
"Which quality is forcing this — latency, cost, availability, security, maintainability, something else? Name the number or condition." |
| Components touched |
"Which of the components in the brief does this decision affect? (≤5)" |
| Prior ADR in play |
"Does this supersede / amend / relate-to / tension any existing ADR?" |
| Decider |
"Who is accountable for this decision? Named human(s)." |
Gate: If 2+ MUSTs come back shallow ("the team," "for performance," "future flexibility"), stop and route to adr-discovery. Do not advance.
Phase 2 — Context
Walk each ADR returned by Phase 1's "prior ADR" question, one at a time. For each, classify in dialogue:
supersedes — this decision replaces itamends — this decision adjusts without replacingrelates-to — this decision shares context but stands alonetension — incompatible without one supersedingunrelated — drop it
Glob the ADR directory once to confirm the architect didn't miss any.
Phase 3 — Options
The architect lists the options. Not the agent. If they offer one option, ask: "What else is realistic?"
Walk each option across four separate exchanges:
- Pro — "What's the single strongest argument for this option?"
- Con — "What's the single strongest argument against this option?"
- Effort — "Roughly: hours, days, or weeks to implement?"
- Risk — "If this option fails, how do you find out and how bad is it?"
Optionally add one missing option the architect didn't name (only if you can name a force they haven't addressed). Then state the strongest counter to their leading choice and wait for their response — don't proceed until they've engaged with it.
Phase 4 — Decide
Four separate exchanges:
- Failure modes — "Name 2-3 ways this decision fails in production." Refuse to advance until the architect names them.
- Scripted challenge — pick one push-back from
references/pushback-patterns.md that matches the leading option, deliver it verbatim, wait.
- Confidence — "On a 1-5 scale, how confident is the decider? What would move them to 5?"
- Review-by date — "On what date or trigger should this decision be revisited?"
RFC routing: If confidence is low, the architect isn't a single named human, or the decision touches > 5 components, propose status: proposed with rfc-deadline (default: two weeks) instead of accepted. ADRs serving as RFCs are still real ADRs — they just have a deadline before they harden. If the team also wants a numeric score, store it in confidence-score; keep confidence as high, medium, or low.
Phase 5 — Draft
Section by section. Confirm each before moving to the next. Frontmatter is the first section drafted, not the last, and it is mandatory — see "Refusal behaviors" below. Hard limits enforced:
| Section |
Limit |
Notes |
| Frontmatter |
YAML between --- fences |
Mandatory. title, status, date, deciders required; supersedes / amends / relates-to populated whenever Phase 2 surfaced a related ADR |
| Title |
One line, imperative verb phrase |
0017. Use Postgres for primary store |
| Context |
≤ 3 sentences |
The forces — not the history |
| Decision |
≤ 3 sentences |
Active voice, present tense |
| Consequences |
Bullets only |
Good, because… / Bad, because… |
| Compliance |
1-3 sentences |
Fitness function snippet allowed |
| Alternatives |
Bullets, one-paragraph each |
One con per alternative is enough |
| More Information |
Optional sub-sections, ### Relationships required if frontmatter relationships exist |
Mirrors frontmatter supersedes / amends / relates-to using the link-prefix vocabulary documented in references/template-fields.md (Supersedes, Superseded by, Amends, Amended by, Related to). Parsers that scan body links instead of frontmatter rely on this section. |
| Notes |
Optional |
PARKED open questions cited here. Not a substitute for the Relationships mirror above. |
Default body structure: unless the project's existing decision log already uses a different convention (Nygard plain, Y-statement, arc42, Tyree-Akerman), default to MADR (currently 4.0.0): ## Context (or ## Context and Problem Statement) → ## Decision (or ## Decision Outcome) → ## Consequences → ## Compliance → ## Alternatives Considered → ## More Information (with ### Relationships when relationships exist). If the project has an existing template, follow it. Upstream MADR template: adr.github.io/madr/, source repo github.com/adr/madr.
Phase 6 — Self-Critique
The architect does not see the Phase 5 output yet. Self-critique against ../_shared/adr-is-not.md first, flagging violations one at a time using this template:
Original: <verbatim line>
Violates: <which rule from adr-is-not.md>
Rewrite: <shorter, stricter replacement>
Apply? (yes / no / adjust)
One violation per message. Wait for the architect's reply before flagging the next.
Show the full final draft only when all violations are resolved or accepted.
Phase 7 — Save
- Glob ADR Explorer-friendly directories first:
docs/adr/, docs/decisions/, docs/architecture/decisions/, **/adr/*.md; also check legacy architecture/decisions/ but warn it may need custom ADR Explorer root configuration. Use the first existing directory; if none, create docs/adr/.
- Auto-number: read existing ADRs, take
max+1, zero-pad to 4 digits.
- Filename:
NNNN-kebab-imperative-title.md (must start with the numeric id).
- Write the file.
- Update the index in the directory's
README.md (create if absent).
- Echo cross-link instructions for
supersedes / amends / relates-to so the architect can update the linked ADRs in a separate pass. Remind them that ADR-graph tooling splits into two families:
- Gray-matter-style parsers (e.g., ADR Explorer) read frontmatter only. The keys
supersedes, amends, and relates-to produce edges. Body prose (superseded-by text on the old ADR, Related ADRs: lines, index-hub links) is invisible.
- Body-scanning parsers (e.g., ADR Manager) walk the rendered Markdown looking for ADR-to-ADR links under MADR-style sections (originally
## Links, now community-conventionally ## More Information with a ### Relationships sub-section). Frontmatter is invisible.
The ADR just saved already contains both because Phase 5 enforces the mirror. The linked ADRs the architect updates in a separate pass must also follow the mirror convention. Use zero-padded four-digit ID strings ("0008") in frontmatter lists for stable rendering, though bare integers also parse. If Accepted ADRs are immutable in this repo, ask whether metadata-only relationship-link maintenance (frontmatter + the body Relationships mirror) is allowed or needs an explicit governance exception.
Template (canonical fields)
YAML frontmatter is mandatory and goes first. The body uses MADR (currently 4.0.0) by default and mirrors every frontmatter relationship into a ### Relationships block under ## More Information so the ADR renders edges in both classes of tooling: gray-matter-style parsers that read frontmatter, and parsers that scan body links under MADR-style sections.
---
title: "<imperative verb phrase>"
status: proposed | accepted | superseded | deprecated
date: 2026-05-20
deciders:
- <named human>
supersedes: [] # ADR ids (zero-padded 4-digit strings) this decision replaces
amends: [] # ADR ids this decision adjusts without replacing
relates-to: # the only three keys that create graph edges in frontmatter-scanning parsers
- id: "0000"
reason: "one-line reason"
tags: []
review-by: 2026-11-20 # or trigger e.g. "100k DAU"
expires: 2027-05-20 # optional; only when expiry is real
confidence: high | medium | low
confidence-score: 4 # optional numeric score
rfc-deadline: 2026-06-03 # only when status == proposed and acting as RFC
---
# NNNN. <Title>
## Context
≤ 3 sentences. The forces.
## Decision
≤ 3 sentences. Active voice.
## Consequences
- Good, because …
- Bad, because …
## Compliance
1-3 sentences. Fitness-function snippet if appropriate.
## Alternatives Considered
- Option B -- one paragraph, single strongest con.
- Option C -- one paragraph, single strongest con.
## More Information
### Relationships
Mirror every frontmatter relationship here using the link-prefix vocabulary. Required when frontmatter `supersedes` / `amends` / `relates-to` is non-empty.
- Supersedes [ADR-0004](0004-old-decision.md) -- replaced because <reason>.
- Related to [ADR-0011](0011-tenancy.md) -- shares the tenancy model.
### Notes
Optional. PARKED open questions cited here.
Mirror both surfaces. Frontmatter feeds gray-matter parsers (ADR Explorer); body ### Relationships under ## More Information feeds body-scanning parsers (ADR Manager). Either surface alone leaves the ADR half-rendered; the two must agree. Full rationale, field semantics, and the link-prefix vocabulary live in references/template-fields.md.
Refusal behaviors
The skill refuses to draft when:
discovery-brief.md has any MUST not CONFIRMED- The architect names "the team" instead of a human as decider
- Failure modes are not articulated (Phase 4, step 1)
- More than 5 components are in scope (route to splitting the decision)
The skill refuses to save when:
- Self-critique flags remain unresolved (Phase 6 not complete)
- Numbering would collide with an existing ADR
- The file does not begin with a
--- YAML frontmatter block containing at minimum title, status, date, and deciders (and supersedes / amends / relates-to whenever Phase 2 surfaced any related ADR).
- Frontmatter populates
supersedes, amends, or relates-to but the body has no ## More Information → ### Relationships mirror, or vice versa. Either surface alone leaves the ADR invisible to half the tooling; the two must agree.
References
references/template-fields.md — full semantics for every frontmatter field and sectionreferences/pushback-patterns.md — scripted push-backs for Phase 4references/rfc-routing.md — when an ADR should be RFC status with a deadline../_shared/adr-is-not.md — the canonical "ADR is not" checklist used in Phase 6- The
adr-discovery skill for upstream context gathering
- The
c4-model skill for diagrams alongside the ADR
- The
adr-critique skill for audits of legacy / external ADRs not drafted via this flow
1---2name: adr-drafting3description: This skill should be used when a decision is ready to become an ADR and the user wants co-thinking rather than template filler. PROACTIVELY activate on "draft the ADR", "write up the decision", "co-think this ADR", "challenge my reasoning", "ADR for X", "MADR for X", "Y-statement for X", "we decided to use X", "co-draft", "ADR drafting", or "scripted push-back." Provides: seven-phase ADR drafting, one-question turns, failure-mode pressure test, and self-critique against the ADR-is-NOT checklist.4---5
6# adr-drafting
7
8Co-drafts an ADR through structured dialogue. The architect never sees a first draft — only the self-critiqued revision.
9
10## Inputs
11
12- **Required:** `docs/architecture/discovery-brief.md` with all five MUSTs `CONFIRMED`. If missing or shallow, this skill refuses and routes to `adr-discovery`.
13- **Optional:** `docs/architecture/open-questions.md`. `PARKED` MUSTs must be cited in the resulting ADR's Consequences.
14
15## Core operating rule
16
17**Never emit more than one question or one step per message.** If a turn contains two `?`, two numbered actions, or runs more than a short paragraph, shorten and ask the most important question first.
18
19## Style
20
21- Direct. No "Great question!", "Excellent point!", or "Solid approach!".
22- Bullet-driven, not narrative.
23- Names specific tech, specific files, specific components — never vague nouns.
24- Pushes back on weak reasoning by quoting the architect's words and naming the rule broken.
25
26## Vocabulary (define on first use)
27
28- **Component** — a runnable / deployable unit (C4 Container), not a code class.
29- **System** — one bounded product per ADR.
30- **Architectural characteristic** — the non-functional quality under pressure.
31- **Tension** — two ADRs that conflict without one superseding the other; must be acknowledged, not hidden.
32- **RFC** — review-gated ADR with a feedback deadline; use when the decision is not yet committed.
33- **Fitness function** — automated check (lint rule, arch test, CI assertion, dashboard threshold) that the decision still holds.
34
35## The seven phases
36
37### Phase 1 — Understand
38
39Read `discovery-brief.md`. Do **not** re-ask anything in it. Ask only for the MUSTs not already confirmed:
40
41| MUST | Default question |
42|---|---|
43| Purpose of the decision | "In one sentence: what decision are we recording?" |
44| Architectural characteristic under pressure | "Which quality is forcing this — latency, cost, availability, security, maintainability, something else? Name the number or condition." |
45| Components touched | "Which of the components in the brief does this decision affect? (≤5)" |
46| Prior ADR in play | "Does this supersede / amend / relate-to / tension any existing ADR?" |
47| Decider | "Who is accountable for this decision? Named human(s)." |
48
49**Gate:** If 2+ MUSTs come back shallow ("the team," "for performance," "future flexibility"), stop and route to `adr-discovery`. Do not advance.
50
51### Phase 2 — Context
52
53Walk each ADR returned by Phase 1's "prior ADR" question, one at a time. For each, classify in dialogue:
54
55- `supersedes` — this decision replaces it
56- `amends` — this decision adjusts without replacing
57- `relates-to` — this decision shares context but stands alone
58- `tension` — incompatible without one superseding
59- `unrelated` — drop it
60
61Glob the ADR directory once to confirm the architect didn't miss any.
62
63### Phase 3 — Options
64
65The architect lists the options. **Not the agent.** If they offer one option, ask: "What else is realistic?"
66
67Walk each option across **four separate exchanges**:
68
691. Pro — "What's the single strongest argument for this option?"
702. Con — "What's the single strongest argument against this option?"
713. Effort — "Roughly: hours, days, or weeks to implement?"
724. Risk — "If this option fails, how do you find out and how bad is it?"
73
74Optionally add **one** missing option the architect didn't name (only if you can name a force they haven't addressed). Then state the **strongest counter** to their leading choice and wait for their response — don't proceed until they've engaged with it.
75
76### Phase 4 — Decide
77
78Four separate exchanges:
79
801. Failure modes — "Name 2-3 ways this decision fails in production." Refuse to advance until the architect names them.
812. Scripted challenge — pick one push-back from `references/pushback-patterns.md` that matches the leading option, deliver it verbatim, wait.
823. Confidence — "On a 1-5 scale, how confident is the decider? What would move them to 5?"
834. Review-by date — "On what date or trigger should this decision be revisited?"
84
85**RFC routing:** If confidence is `low`, the architect isn't a single named human, or the decision touches > 5 components, propose `status: proposed` with `rfc-deadline` (default: two weeks) instead of `accepted`. ADRs serving as RFCs are still real ADRs — they just have a deadline before they harden. If the team also wants a numeric score, store it in `confidence-score`; keep `confidence` as `high`, `medium`, or `low`.
86
87### Phase 5 — Draft
88
89Section by section. Confirm each before moving to the next. **Frontmatter is the first section drafted, not the last**, and it is mandatory — see "Refusal behaviors" below. Hard limits enforced:
90
91| Section | Limit | Notes |
92|---|---|---|
93| Frontmatter | YAML between `---` fences | Mandatory. `title`, `status`, `date`, `deciders` required; `supersedes` / `amends` / `relates-to` populated whenever Phase 2 surfaced a related ADR |
94| Title | One line, imperative verb phrase | `0017. Use Postgres for primary store` |
95| Context | ≤ 3 sentences | The forces — not the history |
96| Decision | ≤ 3 sentences | Active voice, present tense |
97| Consequences | Bullets only | Good, because… / Bad, because… |
98| Compliance | 1-3 sentences | Fitness function snippet allowed |
99| Alternatives | Bullets, one-paragraph each | One con per alternative is enough |
100| More Information | Optional sub-sections, **`### Relationships` required if frontmatter relationships exist** | Mirrors frontmatter `supersedes` / `amends` / `relates-to` using the link-prefix vocabulary documented in `references/template-fields.md` (`Supersedes`, `Superseded by`, `Amends`, `Amended by`, `Related to`). Parsers that scan body links instead of frontmatter rely on this section. |
101| Notes | Optional | PARKED open questions cited here. Not a substitute for the Relationships mirror above. |
102
103**Default body structure:** unless the project's existing decision log already uses a different convention (Nygard plain, Y-statement, arc42, Tyree-Akerman), default to **MADR (currently 4.0.0)**: `## Context` (or `## Context and Problem Statement`) → `## Decision` (or `## Decision Outcome`) → `## Consequences` → `## Compliance` → `## Alternatives Considered` → `## More Information` (with `### Relationships` when relationships exist). If the project has an existing template, follow it. Upstream MADR template: [adr.github.io/madr/](https://adr.github.io/madr/), source repo [github.com/adr/madr](https://github.com/adr/madr).
104
105### Phase 6 — Self-Critique
106
107**The architect does not see the Phase 5 output yet.** Self-critique against `../_shared/adr-is-not.md` first, flagging violations one at a time using this template:
108
109```yaml
110Original: <verbatim line>
111Violates: <which rule from adr-is-not.md>
112Rewrite: <shorter, stricter replacement>
113Apply? (yes / no / adjust)
114```
115
116One violation per message. Wait for the architect's reply before flagging the next.
117
118Show the **full final draft** only when all violations are resolved or accepted.
119
120### Phase 7 — Save
121
1221. Glob ADR Explorer-friendly directories first: `docs/adr/`, `docs/decisions/`, `docs/architecture/decisions/`, `**/adr/*.md`; also check legacy `architecture/decisions/` but warn it may need custom ADR Explorer root configuration. Use the first existing directory; if none, create `docs/adr/`.
1232. Auto-number: read existing ADRs, take `max+1`, zero-pad to 4 digits.
1243. Filename: `NNNN-kebab-imperative-title.md` (must start with the numeric id).
1254. Write the file.
1265. Update the index in the directory's `README.md` (create if absent).
1276. Echo cross-link instructions for `supersedes` / `amends` / `relates-to` so the architect can update the linked ADRs in a separate pass. Remind them that **ADR-graph tooling splits into two families**:
128 - Gray-matter-style parsers (e.g., ADR Explorer) read **frontmatter only**. The keys `supersedes`, `amends`, and `relates-to` produce edges. Body prose (`superseded-by` text on the old ADR, `Related ADRs:` lines, index-hub links) is invisible.
129 - Body-scanning parsers (e.g., ADR Manager) walk the rendered Markdown looking for ADR-to-ADR links under MADR-style sections (originally `## Links`, now community-conventionally `## More Information` with a `### Relationships` sub-section). Frontmatter is invisible.
130 The ADR just saved already contains both because Phase 5 enforces the mirror. The linked ADRs the architect updates in a separate pass must also follow the mirror convention. Use zero-padded four-digit ID strings (`"0008"`) in frontmatter lists for stable rendering, though bare integers also parse. If Accepted ADRs are immutable in this repo, ask whether metadata-only relationship-link maintenance (frontmatter + the body Relationships mirror) is allowed or needs an explicit governance exception.
131
132## Template (canonical fields)
133
134YAML frontmatter is **mandatory** and goes first. The body uses MADR (currently 4.0.0) by default and **mirrors every frontmatter relationship into a `### Relationships` block under `## More Information`** so the ADR renders edges in both classes of tooling: gray-matter-style parsers that read frontmatter, and parsers that scan body links under MADR-style sections.
135
136```md
137---
138title: "<imperative verb phrase>"
139status: proposed | accepted | superseded | deprecated
140date: 2026-05-20
141deciders:
142 - <named human>
143supersedes: [] # ADR ids (zero-padded 4-digit strings) this decision replaces
144amends: [] # ADR ids this decision adjusts without replacing
145relates-to: # the only three keys that create graph edges in frontmatter-scanning parsers
146 - id: "0000"
147 reason: "one-line reason"
148tags: []
149review-by: 2026-11-20 # or trigger e.g. "100k DAU"
150expires: 2027-05-20 # optional; only when expiry is real
151confidence: high | medium | low
152confidence-score: 4 # optional numeric score
153rfc-deadline: 2026-06-03 # only when status == proposed and acting as RFC
154---
155
156# NNNN. <Title>
157
158## Context
159≤ 3 sentences. The forces.
160
161## Decision
162≤ 3 sentences. Active voice.
163
164## Consequences
165- Good, because …
166- Bad, because …
167
168## Compliance
1691-3 sentences. Fitness-function snippet if appropriate.
170
171## Alternatives Considered
172- Option B -- one paragraph, single strongest con.
173- Option C -- one paragraph, single strongest con.
174
175## More Information
176
177### Relationships
178
179Mirror every frontmatter relationship here using the link-prefix vocabulary. Required when frontmatter `supersedes` / `amends` / `relates-to` is non-empty.
180
181- Supersedes [ADR-0004](0004-old-decision.md) -- replaced because <reason>.
182- Related to [ADR-0011](0011-tenancy.md) -- shares the tenancy model.
183
184### Notes
185Optional. PARKED open questions cited here.
186```
187
188**Mirror both surfaces.** Frontmatter feeds gray-matter parsers (ADR Explorer); body `### Relationships` under `## More Information` feeds body-scanning parsers (ADR Manager). Either surface alone leaves the ADR half-rendered; the two must agree. Full rationale, field semantics, and the link-prefix vocabulary live in `references/template-fields.md`.
189
190## Refusal behaviors
191
192The skill **refuses to draft** when:
193
194- `discovery-brief.md` has any MUST not `CONFIRMED`
195- The architect names "the team" instead of a human as decider
196- Failure modes are not articulated (Phase 4, step 1)
197- More than 5 components are in scope (route to splitting the decision)
198
199The skill **refuses to save** when:
200
201- Self-critique flags remain unresolved (Phase 6 not complete)
202- Numbering would collide with an existing ADR
203- The file does not begin with a `---` YAML frontmatter block containing **at minimum** `title`, `status`, `date`, and `deciders` (and `supersedes` / `amends` / `relates-to` whenever Phase 2 surfaced any related ADR).
204- Frontmatter populates `supersedes`, `amends`, or `relates-to` but the body has no `## More Information` → `### Relationships` mirror, or vice versa. Either surface alone leaves the ADR invisible to half the tooling; the two must agree.
205
206## References
207
208- `references/template-fields.md` — full semantics for every frontmatter field and section
209- `references/pushback-patterns.md` — scripted push-backs for Phase 4
210- `references/rfc-routing.md` — when an ADR should be RFC status with a deadline
211- `../_shared/adr-is-not.md` — the canonical "ADR is not" checklist used in Phase 6
212- The `adr-discovery` skill for upstream context gathering
213- The `c4-model` skill for diagrams alongside the ADR
214- The `adr-critique` skill for audits of legacy / external ADRs not drafted via this flow
josiahsiegel