ADR Drafting From a Decision Discussion — With Alternatives Honestly Represented

Tier: Foundation · Workflow area: Documentation

Architecture Decision Records fix this, and AI removes the reason they do not get written: turning a messy discussion into a structured document is exactly the extraction-and-drafting work models do well. The craft is in the honesty constraints — an ADR that strawmans the rejected options is propaganda, and it will not survive the first skeptical reader.

When to use

• •
  A real decision just got made in a meeting, thread, or design review (queue choice, sync-vs-async, buy-vs-build, breaking-change policy) and nobody has written it down.
• •
  You are excavating past decisions from thread archaeology before the context-holders rotate off the project.
• •
  A recurring debate keeps resurfacing because the last resolution was never recorded.

Skip ADRs for trivially reversible choices — an ADR for a lint rule is process cosplay. The bar: would reversing this cost more than a day, or surprise another team?

Prerequisites

• •
  The raw discussion material: meeting transcript/notes, Slack/Teams thread export, design-review comments. More raw is better — do not pre-summarize.
• •
  Your team's ADR template, or the standard one (Status / Context / Decision / Consequences, plus Alternatives Considered). Keep it under a page.
• •
  Whoever holds the decision (you or the tech lead) available for a 10-minute review.

The workflow

1. 1.

   Extract before drafting. First pass is structured extraction, not prose:

   Copy

   Below is the thread where we chose between RabbitMQ, Kafka, and SQS for
   order events. Extract, with no editorializing:
   1. The decision as stated, and who stated it.
   2. Every option discussed, with each argument FOR and AGAINST it as actually
      made in the thread (attribute: "Priya argued...").
   3. Constraints and assumptions cited (team size, ops budget, existing infra).
   4. Open questions raised but not resolved.
   5. Anything decided provisionally or "for now".
   Mark anything you inferred rather than found with [INFERRED].
   

   Read the extraction against your memory of the discussion. This is where you catch the model merging two people's positions or inventing a rationale.

2. 2.

   Draft with honesty constraints. Then:

   Copy

   Draft an ADR from the verified extraction using our template. Rules:
   - Alternatives Considered: present each rejected option's strongest form —
     the argument its advocate would sign off on. No strawmen.
   - The decision rationale may only use constraints and arguments from the
     extraction. If the winning argument was "ops familiarity", say that; do
     not upgrade it to a grand architectural principle.
   - Consequences must include negative ones we accepted (e.g., "SQS ties this
     flow to AWS; multi-cloud portability is explicitly sacrificed").
   - Status: Accepted, dated 2026-07-24. Keep it under one page.
   

3. 3.

   Run the advocate check. Send the Alternatives section to whoever argued for the losing option: "Does this represent your position fairly?" One-line ask, enormous trust payoff — and the single best defense against re-litigation, because the dissenter is now on record that their case was heard at full strength.

4. 4.

   Capture the residue. Open questions from the extraction become tickets or a "Revisit when" clause in the ADR ("Revisit if order volume exceeds 10k/s or we adopt a second cloud"). Explicit reversal triggers are what distinguish an ADR from a monument.

5. 5.

   File it where code review lives. Commit to docs/adr/NNNN-order-event-queue.md via PR — the PR review is the ratification. Link the ADR from the code it governs (module README or top-of-file comment) so future readers find the why next to the what.

Tool variants

• Chat assistant (Claude/ChatGPT): the default — paste thread exports directly; long threads reward large context.
• Claude Code / repo agent: when the discussion lives in PR comments and issue threads, let the agent pull them itself and draft into docs/adr/ in one pass.
• Meeting-platform AI notes (Zoom/Teams/Meet recap): usable as input to step 1; never file a raw meeting recap as an ADR — recaps record who spoke, not what holds.

Verification

• •
  Every claim in the ADR traces to the discussion or is marked as a post-hoc addition; zero surviving [INFERRED] tags.
• •
  The losing option's advocate signed off on the Alternatives section.
• •
  A reader with no context can state, from the ADR alone: what was decided, what it cost, and what would trigger revisiting.
• •
  The ADR is findable from the code it governs, not only from the docs tree.

Pitfalls

• Post-hoc rationalization. The model writes the tidy justification the team wishes it had. If the real reason was "the deadline," the ADR that says so is the one that ages well.
• Strawmanned alternatives. "We considered Kafka but it is complex" — if that survives, nobody who likes Kafka will trust the document, and the debate returns.
• ADR sprawl. Recording every choice buries the ten decisions that matter under two hundred that do not. Enforce the reversibility bar.
• Skipping the human ratification. An AI-drafted, never-reviewed ADR has negative value: it looks authoritative and no one ever agreed to it.

Restricted-environment variant

Decision threads are dense with client names, commercial terms, and internal politics. Redact before pasting into any non-sanctioned tool: client → CLIENT_A, replace commercial figures, drop the HR-adjacent asides entirely. On client engagements, prefer the approved tenant. Fully local: extraction-then-draft works well on an Ollama-hosted model because the task is reorganization, not invention — one of the safest workflows to run entirely offline. The advocate check and ratification PR involve no model at all.

Success criteria

• •
  The decision exists as a one-page ADR, ratified by PR, within a day of being made — not a sprint later.
• •
  Alternatives are represented at full strength, confirmed by their advocates.
• •
  The next time the debate threatens to reopen, someone links the ADR and it actually settles it.
• •
  New joiners cite ADRs when asking "why is it built this way" — the archive is being read, not just written.