MADR decision records

Contract

Enforces the MADR template on every write-up of a decision that has been made: fixed headings, the exact Chosen-option sentence, and Good/Bad consequence bullets. Apply when documenting an architectural or technology choice for the record; not for meeting minutes or for analyzing a still-open choice.

Rules

1. One record per decision. A write-up covering two decisions becomes two records, each

with its own title and full section set — never one combined document.

1. Title = short noun phrase naming the solved problem and its solution, as the top-level

heading: # Store user sessions in the relational database. Never a full sentence, never a question, never a bare topic like "Sessions".

1. Fixed section headings, in this order:

• ## Context and Problem Statement — two to four sentences framing the situation and the

problem; it may end by stating the problem as a question.

• ## Decision Drivers — a bullet list of the concerns and criteria that mattered, one

driver per bullet (* <driver>).

• ## Considered Options — a bullet list of ALL candidate options, the chosen one

included. Each entry is a short option title, not a paragraph of analysis.

• ## Decision Outcome — see rule 4.

1. The outcome opens with the exact sentence form:

Chosen option: "<option title>", because <justification>.

The option title is quoted and must match one entry from Considered Options verbatim. The justification names the driver(s) that settled it (e.g. "only option that meets driver X").

1. Consequences are labeled bullets under a ### Consequences heading inside the Decision

Outcome section:

• Good, because <positive consequence>
• Bad, because <negative consequence>

Include at least one Good, because and at least one honest Bad, because bullet — every real decision has a cost.

1. Optional depth goes below, not inline. Per-option analysis belongs in an optional

## Pros and Cons of the Options section after the outcome, one ### <option title> subsection each — never mixed into the Considered Options list.

Worked example

BEFORE (free prose)
  We talked it over and decided to describe our architecture diagrams as text
  and render them in CI, since exported images kept going stale and could not
  be reviewed in diffs. We also looked at a paid whiteboard tool.

AFTER (conforming record)
  # Render architecture diagrams from text kept in the repo

  ## Context and Problem Statement

  Exported diagram images go stale and cannot be meaningfully reviewed in a
  diff. How do we keep architecture diagrams accurate and reviewable?

  ## Decision Drivers

  * Diagram changes must be reviewable in pull requests
  * Low effort to keep diagrams current
  * No per-seat licensing cost

  ## Considered Options

  * Text-based diagrams rendered in CI
  * Exported images from a whiteboard tool
  * A paid collaborative diagramming service

  ## Decision Outcome

  Chosen option: "Text-based diagrams rendered in CI", because it is the only
  option that makes diagram changes reviewable in a diff while adding no
  per-seat cost.

  ### Consequences

  * Good, because diagram edits show up in review like any other change
  * Good, because CI re-rendering keeps published diagrams current
  * Bad, because complex layouts are harder to fine-tune than in a visual tool

Edge cases & exceptions

• Two decisions arrived together (say, switching CI provider and adopting a merge queue)

→ two records. Each stands alone with its own title, drivers, options, and outcome.

• Only one option was ever on the table → still list it under Considered Options (often

with "Do nothing" as the second option) and still write the Chosen-option sentence.

• The problem is fuzzy → sharpen the Context and Problem Statement by ending it with the

question the decision answers.

• Drivers were never made explicit → derive them from the justification; the driver that

decided it must appear in the Decision Drivers list.

• No downside comes to mind → find the real one (cost, lock-in, learning curve, migration

effort). A record with zero Bad, because bullets reads as advocacy, not a record.

Do / Don't

• Do title the record with a short noun phrase. Don't title it with a sentence or question.
• Do use the exact headings Context and Problem Statement, Decision Drivers, Considered

Options, Decision Outcome. Don't substitute ad-hoc headings like "Background" or "Rationale".

• Do open the outcome with Chosen option: "<option>", because .... Don't bury the choice in

a paragraph.

• Do keep Considered Options to short titles. Don't expand analysis inside the list.
• Do write consequences as Good, because / Bad, because bullets. Don't write a prose

consequences paragraph.

• Do write one record per decision. Don't bundle related decisions into one document.

Common mistakes

• Free-form prose rationale with no fixed sections — the default.
• Ad-hoc headings ("Background", "Why", "Rationale", "Alternatives") in place of the

template's exact headings.

• Stating the choice without the Chosen option: "...", because ... sentence.
• Omitting rejected options, or omitting the chosen option from Considered Options.
• Consequences as an unlabeled paragraph, or only listing the upsides.
• One combined record covering several decisions.

Quick checklist

• Title: # + short noun phrase (problem + solution).
• Sections in order: Context and Problem Statement / Decision Drivers / Considered Options /

Decision Outcome (+ ### Consequences).

• Outcome sentence: Chosen option: "<option>", because <justification>. — option verbatim

from the list.

• Consequences: at least one * Good, because ... and one * Bad, because ....
• Exactly one decision in this record.