ADR Drafting with an Options-Analysis Scaffold

Tier: Foundation · Hands-on time: ~20 minutes

ADRs are the highest-value documentation an architecture practice produces and the most reliably skipped, because the writing cost lands after the decision's energy is spent. Documentation drafting is the most established AI use in the architect's toolkit, and ADRs are its best case: the format is rigid (context, options, decision, consequences), the content already exists in notes and chat threads, and the failure mode — a plausible-sounding rationale the room never actually voiced — is checkable by the people who were there. Consistent house style across dozens of ADRs is a bonus AI provides for free.

When to use

• •
  A design discussion just settled something and the reasoning is still warm — the ideal moment, and the one this playbook is sized for.
• •
  A decision exists in a thread or meeting notes and needs formalizing before the reasoning evaporates.
• •
  Your ADR log has a consistent-style problem: five authors, five formats, unreadable as a set.

Skip AI when the decision is not actually made — an ADR drafted to look decided pressures the room to ratify the draft. Decide first, record second.

Prerequisites

• The raw materialmeeting notes, the chat thread, whiteboard photos, or your own bullet summary of the discussion.
• An LLM chat assistanta Claude Project holding your ADR template and two exemplar ADRs produces house-style output without re-prompting.
• Your MADR-style templatenumber, title, status, context, decision drivers, options considered, decision outcome, consequences (good and bad), links.
• The decision, actually madeincluding what was ruled out and why, even roughly.

The workflow

1. 1.

   Dump the raw material without cleaning it. Paste the notes as they are — half-sentences, dissent, dead ends included. The dead ends are the options-considered section; the dissent is the consequences section. Pre-cleaning the notes throws away exactly what the ADR format exists to preserve.

2. 2.

   Scaffold with the decision line withheld.

   Copy

   Draft an ADR from the discussion notes below, using our MADR template
   (attached). This records Orbit's choice of state store for the
   orbit-docs-copilot session layer.
   
   Rules:
   - Fill: title, context, decision drivers, options considered (with
     the pros/cons actually raised in the notes — quote or closely
     paraphrase; do not add textbook pros/cons nobody voiced), and
     consequences as discussed.
   - Leave the "Decision outcome" section containing exactly:
     [DECISION — ARCHITECT WRITES THIS]
   - Where the notes are ambiguous about why an option was rejected,
     write [UNCLEAR — confirm with room] rather than inventing a
     rationale.
   - Match the voice and heading conventions of the two example ADRs.
   ###
   [paste notes]
   

3. 3.

   Write the decision outcome yourself. Two or three sentences, in your own words: what was decided and the one reason that actually carried the room. This is deliberately the human step — the decision line is the sentence future architects will quote, and it should be the sentence the decision-maker actually means, not the model's synthesis of the vibe.

4. 4.

   Resolve every [UNCLEAR] flag with a person, not the model. Each flag is a question to whoever raised the point. This is cheap now — a Slack message while memory is fresh — and expensive in six months when the ADR is the only witness. An ADR shipped with invented rejection rationales poisons the decision log's credibility wholesale.

5. 5.

   Red-team the high-stakes ones. For decisions with real blast radius, run the draft through a pb-11-style pass before filing: "Attack this ADR: which decision drivers are unweighted assertions, which consequences are missing, what would a reviewer who preferred option B say is misrepresented?" Fold in what survives your triage. Routine ADRs skip this step; platform-choice ADRs should not.

6. 6.

   File, number, and link it while the meeting is findable. Commit to the ADR directory, update the index, and link the ADR from the design doc and the ticket that triggered it. Backlink the source notes. An ADR nobody can find from the code it governs is a diary entry, not a record — and this corpus is what pb-18 later turns into a queryable knowledge base.

Verify before you trust it

• The room recognizes itself. Send the draft to two attendees with one question: "is this what we decided, and why we decided it?" This is the only authoritative check on a record of a human decision — the source documents cannot arbitrate what the meeting meant.
• No textbook options crept in. Check options-considered against the notes: every pro and con should trace to something actually said (or your own added point, which you then own). Models pad comparisons with generic trade-offs, and padded ADRs teach future readers reasoning that never happened.
• Quotes and attributions are real. If the draft attributes a position to a person, verify it — misattributed dissent in a permanent record is a relationship problem, not a typo.
• Service claims get the register treatment. ADRs about platform choices cite limits, pricing, or capabilities; each such claim needs the pb-05 check with a today-dated source before the ADR is marked accepted. Decision records outlive pricing pages.

Restricted-environment variant

Design discussions name client systems and commercial context. Under a restrictive pb-03 ruling: redact the notes to placeholders before pasting (the MADR structure survives redaction; restore names in the filed copy), or run drafting on the client-tenancy endpoint or a local Ollama model — ADR scaffolding is well within a local model's range when the template travels in the prompt. The decision line, the [UNCLEAR] resolutions, and the room's sign-off are human steps in every environment, which is most of what makes the record trustworthy.