# Decisions: choosing with evidence, and recording it

Load for any choice that matters: a platform, supplier, part, provider, library, venue, design,
route or tool; any decision that would be costly to reverse; and whenever a recorded decision's
reopening condition fires. Decisions are recorded as ADRs (`../templates/adr.md`).

Asked to choose, an agent searches, takes the first result with a free tier, and then writes a
comparison that supports it. It looks researched, and it is a habit with a table attached. The
same failures appear whether the choice is a database, a board, a caterer or a model provider.

## Which decisions need evidence

1. **State the question as the job, not the product.** "Where do 1,000 GB of audio live, so that
   listeners can download 5,000 GB a month for under $60?", not "should we use CloudA?". If the
   question names an answer, the real question is what that answer was meant to do, and it
   becomes one option among several.
2. **Name what it serves:** the objective, a measure, a journey, a requirement or a constraint. A
   choice that serves none of them is not needed; say so and stop.
3. **Set the stakes first, and let them set the effort.** What would a wrong choice cost, and how
   long would it take to reverse?
   - **Costly to reverse** ("a one-way door"): it holds the data or the people; it fixes the data
     model, identifiers, a public interface (and who operates each action through it: a person, an
     agent, automation) or public URLs; it has lead time or tooling; it is built
     into firmware or hardware in people's hands; it is the language, runtime or platform; it is
     the licence or a name people will learn; it spends money or commits the owner to a person
     or supplier. Make it for the size and shape the objective implies, not only today's.
   - **Cheap to reverse** ("a two-way door"): everything else. Two options, two backings (at
     least one verified by you), and the choice behind a seam. An hour's work, not a week's.
4. **Match the effort to the stakes.** Spending costly-decision effort on a cheap choice is how a
   project spends its budget on trivia; an irreversible choice made quickly is how it ends up
   rebuilt.
5. **Defer what a seam can hold.** Do not make a costly decision before the evidence allows;
   where one module, interface or configuration key can hold it open, defer it and write down
   until when.
6. **Read the earlier decisions this one depends on or contradicts** before starting.

## Options

- **Generate widely before narrowing.** The list includes at least:
  - doing nothing, or keeping what exists;
  - configuring or reusing something the project or owner already has;
  - building or making it (a script, a module, a tool, a circuit, a jig);
  - each serious thing to buy or use, commercial, open-source or community-run;
  - combinations of these.
- **For hardware and parts:** part families, and a second source for each part.
- **No free passes:** include the option the owner suggested and the one found first, and give
  neither a pass.
- **Nothing is excluded for being unusual, large or unfamiliar.** An option is excluded by
  evidence, and the reason is written down.
- **If every option fails a hard limit, the limit is the problem to solve:** find what would
  move it (a funding route, a phased approach, a different design, a tool built for the job) and
  cost that route. If no feasible authorised route has been demonstrated, say so with evidence,
  remaining uncertainties and the smallest constraint change that would enable one; take that
  proposal to the authorised decision-maker instead of inventing a workable option.
- **Choose one, several, or a sequence:**
  - **one**, when it passes the hard limits and is clearly preferable on the justified criteria;
  - **a portfolio**, each option where it is strongest (one place keeps the masters, another
    serves them);
  - **a sequence**: start with one behind a seam, and write now the condition that triggers a
    switch (a measure, a price, a date, a count of incidents) and the plan for switching;
  - **an experiment**, when evidence cannot separate two options and trying is cheap: run both
    for a fixed period, measure them on the criteria, decide on a date set in advance.
- **Several outcomes may be defensible.** Define improvement for the accepted objectives,
  affected people, constraints and time horizon. Compare hard limits first, then material
  tradeoffs. If priorities or evidence do not separate the options, retain the serious
  alternatives and explain which is preferable under which conditions. Do not manufacture a
  winner with invented scores or weights. Compare the combined costs, dependencies, risks and
  limits of a portfolio; good parts do not automatically make a good whole.
- Challenge material premises before commitment (`quality.md §Challenging recommendations and
  existing methods`). The owner's named option and an accepted method can both be evaluated;
  that does not authorise a contradictory change.

## Criteria before scores

1. **Write the criteria and any justified weights before scoring candidates, and record them**
   with the measurement scales and rationale so the order shows in the history. Use a method
   proportionate to the stakes and evidence, not a fixed scoring recipe. A simple weighted table
   is not a claim of formal decision analysis or government/enterprise conformity.
2. **Take every criterion from something named:** a measure, a journey, a constraint (the budget,
   a licence, a lead time, the skills of whoever will maintain it) or a risk. Popularity, stars,
   "modern" and "developer experience" are easy to score and connected to nothing.
3. **Hard limits** (under the budget, an open licence, available within the lead time) are pass
   or fail, not weights.
4. **Build the comparison table:** options as rows, criteria as columns, each cell with its
   evidence and source, hard limits marked. Never adjust the weights after scoring until the
   favourite wins.

## Evidence

- **Primary sources:** price lists, datasheets, licences, documentation, status and incident
  history, changelogs, open issues that match this use, and the terms on data ownership, export
  and limits. A vendor's claim, a vendor's benchmark, or a vendor's comparison with its
  competitors is marketing until a second source or a measurement agrees.
- **Your own measurement, shaped like the use:** a spike or prototype on the project's own data
  and target hardware; a benchmark at the target scale; a calculation with its units; a
  simulation with its model and assumptions stated. A benchmark on 100 rows says nothing about
  ten million; a laptop on office fibre says nothing about phones on 4G; a demo board on the
  bench says nothing about a field.
- **Label every piece of evidence by its kind:** Measured, Calculation, Simulation, Proof,
  Prototype, Test or Source.
- **Every decision has at least two backings, and at least one is something you ran, worked out
  or built** rather than read.
- **A costly-to-reverse decision needs two different kinds of evidence** (a calculation and a
  measurement; a primary source and a prototype), three or more options, a way out, a reopening
  condition, and the owner's approval or explicit scoped standing authority covering the choice.
  Two articles quoting the same benchmark are one piece of
  evidence.
- **Gather the real numbers:** current and expected usage, sizes and rates, measured wherever
  possible; and find where the choice plugs into the code, circuit or process, which is where
  the seam goes.

## Redo every number

- **Recompute every cost, capacity and rate yourself, with units,** at today's size, at the
  target size and at ten times the target.
- **Look for the usual slips:** gigabytes read as terabytes, a monthly price as a yearly one,
  microamps as milliamps; a term left out (egress, a per-seat fee, a per-request charge, the
  standby current, delivery, tax).
- **Name the term that dominates,** which is often not the headline price.
- **Name the assumption that would flip the decision,** and how far it would have to move.
- **Check plausible scenarios and uncertainty:** changes in usage, cost, priorities and evidence
  that could change the recommendation, using justified ranges rather than invented precision.
  Distinguish measured advantage, preference-dependent choice and evidence that cannot separate
  alternatives. Gather more evidence when its likely effect on the action justifies cost and delay;
  otherwise take the justified reversible next step within delegation and record its switch condition.

## A way out and a reopening condition

- **Keep the way out cheap:** put the choice behind a seam (one module, one interface, one
  configuration key, one purchase order); own the identifiers and the data format; keep public
  URLs on a domain the project controls; test an export once.
- **Write the exit down:** what leaving would cost, and how it would be done.
- **Write the condition that reopens it** (a measure, a price, a date, a count of incidents).
  Only that condition or an explicit request from the authorised decision-maker reopens it;
  a newer article or a change of mood alone does not. Reopening is a review, not approval to
  replace the decision. Apply the existing evidence and approval requirements. Evidence may
  justify proposing reopening even when the original condition was too narrow; do not change
  the decision silently. Another acceptable option alone does not reopen an accepted choice.
- **At every review, evaluate each accepted decision's reopening condition** with today's numbers.
  For each that has fired, reopen the decision, or record why it stands, with the number. A
  condition that could never fire is itself a finding: rewrite it.
- **Deferred decisions** are recorded with the seam that holds them open and the condition that
  will close them.
- **Between two close options, take the one that is easier to leave.**

## Recording and superseding decisions

- **One ADR per decision** (`../templates/adr.md`, in MADR form): the question and what it
  serves; whether it is costly to reverse, and why; the criteria; the options; the evidence, each
  labelled by kind; the decision; the exit; the reopening condition; the status (proposed,
  accepted, rejected, deprecated, superseded); who approved it, for a costly one.
- **Number ADRs in order and keep each file's number unique.** A superseded ADR names the ADR that
  replaced it, and the replacement names the one it supersedes.
- **Record a decision before, or with, the change that needs it.**
- Keep the accepted core and repeated policy/values consistent with their authoritative sources
  (`../SKILL.md §3. Work records`); do not leave superseded material claiming current authority.
- **Design decisions are decisions like any other:** the flow chosen, the interaction model, the
  information architecture, the design tokens, the name and the voice. The product's name,
  anything people learn by habit, and a machine interface others will build on are costly to
  reverse; a colour is not.
- **Review checklist for an ADR** (applied by a verifier who is not its author):
  - it states what it serves, and that thing exists in the records;
  - it lists two options, or three or more if it is costly to reverse, including doing nothing,
    building and combining where they apply;
  - it has at least two backings, labelled by kind, at least one verified; two different kinds
    for a costly one;
  - the criteria were recorded before the scoring;
  - the numbers were redone, and the flipping assumption is named;
  - for a costly one: the exit is written and the approver is named;
  - an accepted decision has a reopening condition;
  - a superseded one names a real successor;
  - no current work serves a rejected or superseded decision.

## Asking the owner

- **When the choice needs the owner to pay, sign up, approve or accept a risk, send one message**
  with: the comparison; the recommendation and its cost now and at the target size; the
  strongest alternatives, their tradeoffs and the conditions under which each is preferable;
  any unresolved superiority; and what happens if they say no.
- **Then stop asking.** A no is a constraint; plan around it. Present the alternatives and the
  cost of each; recommend once, and never nag toward an option.
- **A decision the briefing delegated** is made without asking, within its standing limits, and
  recorded with how to undo it (`autonomy.md §Choices on the owner's behalf`); only what the
  briefing kept for the owner goes to them, and the work carries on meanwhile.
- **For a costly decision outside explicit scoped standing authority, wait for approval where
  the harness can pause.** Where it cannot, record the decision as proposed and do not act on it.