Skip to content

Library · Data Practice OS

Options paper and fact check

Template · Published · Source reviewed

Use an Options paper for any decision big enough to need an ADR. The paper does the analysis; the ADR records the outcome; the Decision register lists both.

Adapted from a platform team's Options paper template (draft, 27 Oct 2026) and the review of its Hosting MCP services in AWS paper. The method has been used on eight the platform team papers so far.

Rules for authors

  1. Write the sections in order. Write the problem, the goal and the current position before you list options.
  2. Patterns before products. Name no product before "Options considered". Products are possible implementations of a pattern.
  3. Give every item an ID (D1, G1, C1, U1, Q1, E1, S1, and so on), and refer to items by ID.
  4. If the evidence does not establish something, write an open question. Do not write an answer.
  5. Status on every claim. Separate directions (discussed, not approved) from decisions. A criterion that rests only on a direction is not a gate.
  6. Write the Summary last, using the same scores as the comparison.

The template

# Options paper: <the decision, with no product names>

## Document control
| Status | Draft / In review / Decided (date). Say if the team has NOT agreed the recommendation |
| Author | <role> |  | Reviewers | <roles> |  | Decision owner (Accountable) | <one role> |
| Consulted | <roles> |  | Decision record | <ADR link and register row, when decided> |

## Summary            (six rows: Decision, Recommendation + score, Runner-up + score, Why, What we give up, Blocking questions)
## Why are we looking at this?     (D1..)  Directions to evaluate (AD1..), discussed but not approved
## Goal                            (G1..)  plus measures you can check (M1..)
## Current position                (C1..)  capability, standards, decisions that exist now
## Gap and uncertainty             (U1..)
## Decision required               the numbered decisions this paper makes
## Why now?
## Open questions                  (Q1..)  Still open / Direction set, team to agree
## Scope                           in / out
## Requirements and evaluation criteria   (table below)
## Options considered              patterns, then implementations; pros and cons; rejected options with reasons
## Evidence                        meeting evidence (T1.., with status) and technical evidence (E1.., with a source and a date)
## Option comparison               H/M/L per criterion with a reason; weighted totals; what the totals show; trade-offs
## Security · Cost · Ownership
## Recommendation                  rationale; traceability (table below); risks and controls
## Supporting decisions
## Sources                         (S1..) with the date read; list sources the network blocked

Criteria and scoring

# Criterion Description Driven by Weight Gate source
1 G1, U2 3 = must, 2 = important, 1 = nice
  • Points: H = 3, M = 2, L = 1, multiplied by the weight. A high score is always good, so for effort, H means low effort.
  • Gates (Gate criterion): an option that fails a gate leaves the comparison, whatever its total. Name the source of every gate. With no source, it is a weighted criterion, not a gate.
  • Unknowns: score ?. Publish no total while a must-have criterion is ?. Mark totals that rest on an assumption as provisional.
  • What the totals show: state the order and the margin. Then test sensitivity: does the order change if a contested weight moves, or if the criterion that favours the author's own earlier work is removed?
  • The recommendation must follow from the scores. If it does not, a criterion is missing (often delivery risk or approval lead time). Name it and score it, or state the reason openly.

Traceability

Goal Drivers Gaps Decision Criteria How the option meets it Evidence Trade-off accepted
G1 D1 U1 1 1, 6 E1, E5

Fact check (kept beside the paper, not in it)

Reviewers check facts separately, in their own file. The author decides what changes. A paper is never silently rewritten.

# Claim Section Result Source and date
F1 Options: 3 Confirmed / Changed / Partly changed / Open

New facts found during the check go in their own list. Overturned facts go back into the paper before a decision. In the platform team's MCP hosting review, 3 of 14 claims were overturned and 5 new facts emerged. That was enough to change the recommended path.

Review checklist

  • [ ] Major issues: does the recommendation follow from the criteria?
  • [ ] Facts the check changed are reflected in the paper.
  • [ ] The comparison table uses the paper's own criteria.
  • [ ] Missing content: diagrams, document control, owner, accountable role.
  • [ ] Small corrections.

Spikes instead of building twice

When the interim path would be thrown away (for example a public front door later replaced by a gateway), run a time-boxed spike with written pass and fail conditions first. Include known hard cases. Decide from the spike result.