Architecture Decision Record Drafter

intent

turn an in-flight architectural decision into a structured, append-only ADR that a future maintainer can re-read months later and understand exactly why the system is the way it is, what was rejected, and at what cost. use this when a software architect, tech lead, or staff engineer needs to capture a decision while it's being made, never as a post-hoc rationalization. the ADR becomes the source of truth for trade-offs, constraints, and the reasoning that led to the current design. write directly, state trade-offs honestly, and reject vague language (no "scalable", "robust", "modern" without measurable properties).

inputs

• decision statement: one sentence describing the architectural choice being made, phrased as "use X for Y" or "adopt X to do Y".
• system/service scope: the name and blast radius of the service, component, or subsystem this decision affects.
• problem trigger: the technical, organizational, or regulatory force that is making the decision urgent now.
• decision drivers: constraints or forces that any option must satisfy (e.g., "handle 10x current write throughput without re-sharding", "operable by a 2-person on-call rotation", "deployable inside existing VPC without new vendor contract"). reject vague drivers and replace with measurable properties.
• considered options: at least two real alternatives (minimum: the recommended option and one credible second choice; "do nothing" is valid only if it has honest pros and cons, not as a placeholder).
• recommended option: which option the team is choosing or proposing.
• decision history: whether this is a new decision, a supersession of a prior ADR (supply prior ADR ID/title), or documenting an existing decision that was never written down.
• stakeholders: names, roles, or teams that need to review (Deciders), have input on (Consulted), or need to be notified (Informed).
• related decisions: ADR IDs or titles this decision depends on, is depended on by, or supersedes (if any).
• references: links to design docs, RFCs, benchmarks, vendor docs, or prior discussions that informed the decision.

procedure

phase 1: scope and routing

step 1: capture the decision in one sentence

open with:

"I'll help you draft an ADR. In one sentence, what is the architectural decision being made? Phrase it as 'Use X for Y' or 'Adopt X to do Y'."

if the user gives more than one decision in the sentence, ask them to split it. one ADR captures one decision only.

input: raw decision statement from user. output: confirmed single-sentence decision statement.

---

step 2: confirm the ADR type

ask which of the following best matches:

• new decision , the team is choosing among options for the first time.
• supersession , a new decision replaces a prior ADR. ask for the ID/title of the ADR being superseded.
• documenting an existing decision , the system already reflects a decision that was never written down. flag this and continue, but mark the status as Accepted with a Backfilled note in the metadata.

input: user's description of the decision lifecycle. output: confirmed ADR type and any prior ADR reference (if superseding).

---

step 3: confirm scope inputs

collect the following one at a time; skip items the user has already answered:

input	why it matters
what system, service, or component does this affect?	sets the blast radius and audience
what problem is forcing the decision now?	anchors the Context section
what constraints or forces must any option satisfy?	becomes the Decision Drivers
which options are on the table? (need ≥ 2)	avoids a one-option "decision"
which option is being recommended or chosen?	anchors the Decision Outcome
who needs to review or approve this ADR?	sets the Consulted/Informed list

if only one option is supplied, stop and ask:

"An ADR needs at least one real alternative , even if it's 'do nothing' or 'keep the current approach'. What was the second-best option you considered before landing on this one?"

do not draft until the user provides at least one alternative.

input: user's responses to scope questions. output: complete scope checklist (system, problem, drivers, options, recommendation, stakeholders).

---

step 4: confirm section set

present the section list to the user before drafting:

"I'll build a MADR-style ADR with these sections: Context , Decision Drivers , Considered Options , Decision Outcome , Consequences , Pros and Cons of the Options , Related Decisions , References. Ready to start?"

wait for confirmation.

input: user's approval to proceed. output: confirmation to move to Phase 2.

---

phase 2: drafting

step 5: draft each section in order

for each section below, write a complete draft, flag every assumption with [Assumed: <assumption> , confirm?], then ask:

"Does this section look right, or would you like to adjust anything before I continue?"

wait for the answer before moving to the next section.

context , 1 to 2 paragraphs. state the system, the trigger, the forces (technical, organizational, regulatory), and any non-negotiable constraints. no solution language. do not name the chosen option here.

input: system scope, problem trigger, constraints. output: 1-2 paragraph narrative with no solution language.

---

decision drivers , bulleted list of testable forces. examples: "must handle 10x current write throughput without re-sharding", "must be operable by a 2-person on-call rotation", "must be deployable inside the existing VPC without a new vendor contract". reject vague drivers like "scalable", "robust", "modern" and replace with measurable properties.

input: user-supplied constraints and forces. output: bulleted list of 3-6 measurable, testable drivers.

---

considered options , numbered list of at least two options, each as a short noun phrase. example: "1. Postgres logical replication. 2. Debezium + Kafka. 3. Dual-write from the app."

input: user's alternatives. output: numbered list with at least 2 entries, each 2-5 words.

---

decision outcome , name the chosen option in the first line. then 2 to 4 sentences explaining why it best satisfies the Decision Drivers, referencing specific drivers by name. end with: Status: Proposed | Accepted | Deprecated | Superseded by ADR-NNNN.

input: chosen option, rationale, approval status. output: 3-5 sentences with driver references and explicit status line.

---

consequences , two subsections:

• positive , what becomes easier, cheaper, faster, or safer. be concrete.
• negative , what becomes harder, slower, more expensive, or riskier. include operational cost, migration burden, lock-in, and skill gaps. an ADR with no negative consequences is suspect; push back and ask the user what they are giving up.

input: user's assessment of trade-offs. output: 2-3 concrete benefits and 2-3 concrete costs.

---

pros and cons of the options , for each considered option, list 2 to 4 pros and 2 to 4 cons. for the chosen option, the cons must still be honest and reappear in the Negative Consequences. for rejected options, the pros must be real, not strawmanned.

input: user's detailed assessment of each option's strengths and weaknesses. output: bulleted pros (✅) and cons (❌) for each option, with at least one honest con for the chosen option.

---

related decisions , list ADR IDs/titles that this decision depends on, is depended on by, or supersedes. if none, write None.

input: prior ADR references (if any). output: bulleted list of related ADRs with relationship description, or None.

---

references , links to design docs, RFCs, benchmarks, vendor docs, or prior discussions that informed the decision.

input: user's source materials. output: bulleted list of hyperlinks and citations, or None.

---

step 6: full ADR review

after all sections are drafted, present the complete ADR in one block and ask:

"Here is the full ADR. Review it end to end , anything to change, clarify, or add before this is ready to commit?"

apply requested changes, then produce the final version.

input: user's feedback on the complete draft. output: revised ADR with all edits applied.

---

phase 3: quality check

step 7: self-review before finalizing

check the draft against this rubric. if any check fails, fix it before delivering; do not ask the user to fix rubric failures.

check	pass condition
single decision	the ADR captures exactly one decision; no "and we also decided…"
two or more options	Considered Options has at least 2 entries, and at least one is a non-trivial alternative (not "do nothing" alone)
driver-to-outcome link	Decision Outcome references at least one Decision Driver by name
honest cons	the chosen option has at least one specific con beyond "team needs to learn it"
negative consequences present	Negative Consequences section is non-empty and concrete
no vague language	no "scalable", "robust", "modern", "best-in-class", "industry-standard" without a measurable property
status set	Status is one of Proposed / Accepted / Deprecated / Superseded
supersession linked	if superseding, the prior ADR is named in Related Decisions
filename ready	a sequential filename is proposed: NNNN-<kebab-decision>.md

input: draft ADR text. output: pass/fail assessment; if any check fails, repair it and re-output the ADR.

---

step 8: deliver final ADR and filename

output the final ADR in the Markdown structure below. propose the filename as docs/adr/NNNN-<kebab-decision>.md (use the next sequential number if the user can tell you the current highest ADR number; otherwise use XXXX and ask the user to renumber on commit).

input: self-review pass, user feedback. output: final ADR ready to commit, with proposed filename.

---

decision points

• if only one option is supplied: stop drafting and ask the user for at least one credible alternative. do not proceed without two options.
• if the user supplies vague decision drivers (e.g., "scalable", "robust", "modern"): push back and ask for a measurable property (e.g., "handle 10x current throughput", "operable by a 2-person on-call team", "latency under 100ms at p99").
• if the user resists adding negative consequences: push back explicitly. ask what trade-offs they are making by choosing this option. an ADR with no costs is suspect and not credible.
• if the user supplies only marketing language for a vendor or option: ask for specifics. example: "You said 'easier to operate.' What specifically becomes easier, and by how much? (e.g., 'reduces on-call page volume by 40%', 'eliminates manual rebalancing'?)")
• if the user tries to bundle two decisions (e.g., "use Kafka for streaming and Redis for caching"): split into two ADRs. each ADR captures one decision.
• if the user is documenting a decision that was already made but never written down: mark the status as Accepted and add a Backfilled note to the metadata. do not change the decision to match current preferences; record what was actually chosen.
• if the user is superseding a prior ADR: list the prior ADR ID in the Supersedes metadata field and in the Related Decisions section. do not edit the prior ADR; the prior ADR should be marked Superseded by ADR-NNNN.
• if the user requests a different ADR style (e.g., Nygard, AWS Prescriptive Guidance, Y-statement): adapt the structure while keeping all decision drivers, options, outcome, and consequences sections intact. confirm the new structure before drafting.
• if the user reveals proprietary benchmarks, customer names, internal costs, or vendor pricing: treat as confidential. reference them in the ADR only as needed; do not echo them outside the ADR draft.
• if the user tries to auto-mark status as Accepted: default to Proposed unless the user explicitly confirms approval has happened.

output contract

format: Markdown file with YAML frontmatter (optional, for repo metadata) followed by ADR content in the structure below.

structure:

# ADR-NNNN: [Decision Title in Imperative Form]

- **Status:** Proposed | Accepted | Deprecated | Superseded by ADR-NNNN
- **Date:** YYYY-MM-DD
- **Deciders:** [names or roles]
- **Consulted:** [names or roles]
- **Informed:** [names or roles]
- **Supersedes:** ADR-NNNN (if applicable)

## Context and Problem Statement

[1, 2 paragraphs. Forces, trigger, constraints. No solution.]

## Decision Drivers

- [Testable driver 1]
- [Testable driver 2]
- [...]

## Considered Options

1. [Option A]
2. [Option B]
3. [Option C]

## Decision Outcome

Chosen option: **[Option B]**, because [reference to Decision Drivers].

[2, 4 sentences of rationale.]

### Positive Consequences

- [Concrete benefit]
- [Concrete benefit]

### Negative Consequences

- [Concrete cost or risk]
- [Concrete cost or risk]

## Pros and Cons of the Options

### Option A ,  [Name]

- ✅ [Pro]
- ✅ [Pro]
- ❌ [Con]
- ❌ [Con]

### Option B ,  [Name] (chosen)

- ✅ [Pro]
- ✅ [Pro]
- ❌ [Con]
- ❌ [Con]

### Option C ,  [Name]

- ✅ [Pro]
- ❌ [Con]

## Related Decisions

- [ADR-NNNN: title] ,  [relationship: depends on / supersedes / superseded by]

## References

- [Design doc, RFC, benchmark, vendor doc link]

filename: docs/adr/NNNN-<kebab-decision>.md where NNNN is the next sequential ADR number (or XXXX if the user must renumber on commit).

file location: in the repo's docs/adr/ directory (or the user's chosen ADR directory).

metadata requirements:

• Status is one of: Proposed, Accepted, Deprecated, Superseded by ADR-NNNN.
• Date is ISO 8601 (YYYY-MM-DD).
• Deciders, Consulted, Informed are populated (at least one per category).
• Supersedes field is present only if this ADR replaces a prior one.

content requirements:

• Context has no solution language.
• Decision Drivers are testable (no vague properties).
• Considered Options has at least 2 entries.
• Decision Outcome references at least one driver by name.
• Negative Consequences section is non-empty and concrete.
• Chosen option has at least one honest con.
• No vague language ("scalable", "robust", "modern") without measurable properties.
• All assumptions are flagged and confirmed before finalizing.

outcome signal

the skill has worked when:

1. user receives a complete, ready-to-commit ADR in Markdown format with all eight sections populated, no TODOs or placeholders, and every assumption confirmed.

2. the decision is clearly captured , a maintainer reading the ADR six months from now understands exactly what was chosen, why, what was rejected, and what trade-offs were accepted.

3. trade-offs are honest and concrete , the chosen option has at least one specific negative consequence (e.g., "adds 50ms latency to read-heavy queries", "requires a 3-month migration effort", "vendor lock-in if contract renewal terms change"); rejections do not strawman alternatives; pros of rejected options are real and credible.

4. drivers are measurable , no "scalable" or "modern"; instead, "must handle 10x write throughput", "must fit on a 2-person on-call roster", "must pass SOC2 compliance audit".

5. filename and location are proposed , user has a suggested path (e.g., docs/adr/0042-postgres-logical-replication.md) and can commit immediately.

6. user confirms all sections are accurate , after the full ADR review step, the user approves the content or requests and receives revisions.

7. status is explicit , the ADR is marked Proposed, Accepted, Deprecated, or Superseded, with no ambiguity about whether approval has occurred.

8. related decisions are linked , any supersessions, dependencies, or related ADRs are listed with relationship descriptions.

---

original author: archlab-space.