ADR-307: A decision names what should be observable when it holds¶

Summary¶

Decided: a decision may carry observable: what someone should be able to see, run or try when the decision holds. Its shape is loose, because the work varies. It is optional on every decision, and it may be added or refined after acceptance. When a decision is handed to the operator, the agent demonstrates its observables, where that is possible, before asking.
Trades away: a checkable form. A loose field can't be verified by the tool, so an observable is only as good as its author makes it.
One-way? No. The field is optional, so removing it later changes no record's validity.
Probes: Confident (flexible-shape): a free-form list fits the range of work, from a command's output to a page to click through. Not confident (optional-unused): whether an optional field gets used at all, or whether the handover guidance alone carries it.
Inversion: at one end the record is prose to be read, and consideration rests on reading. At the other end every decision carries a runnable check the tool enforces, which fits commands and misses everything seen by eye. This decision names what to observe, leaves its form open, and puts the demonstration in the conversation.

Context¶

considered records the operator's words on a decision, but nothing ties those words to having seen the work. Reading a record is reading about the act. Experiencing what the software does is the missing piece, and a decision record can promote it by saying what should be observable once the decision holds.

cut and retire decisions already have an observable end in enacted, the commit where the removal landed. add and change decisions say what was decided, but not how anyone would see that it holds.

Decision¶

1. The observable field¶

A decision may carry observable, a list. Each entry is either a line of plain words or a mapping whose keys the author chooses to suit the work:

observable:
  - "tier 2 adr-migrate passes 10 of 10"
  - see: a record scanned and applied comes back byte-identical
    run: bash tests/adr-import-roundtrip.sh
  - see: the evidence page renders the findings table
    url: https://claude.ai/artifact/…

see and run are conventions, not requirements. A screenshot path, a URL, a scenario name or a step-by-step description are equally valid. Lint checks only that observable is a list of strings or mappings.

2. Optional, and open after acceptance¶

No decision is required to carry an observable. observable joins the fields that may change after a decision leaves proposed (ADR-304 §4, mutable_after_accept), because what shows a decision holding often becomes clear only once it is built.

3. Asked for when drafting, demonstrated in the handover¶

When an agent drafts an add or change decision, it asks the operator what should be observable once the decision holds. The operator can name an observable, decline, or hand the observing to the agent. In the last case the agent works out what to observe, runs the work and iterates until it can show the outcome, as the develop loop does, and then writes the observable it used into the record.

When a decision with observables is handed to the operator, the agent demonstrates them, where possible, as one step of the flow: it runs the command, shows the output or a screenshot, or opens the page. It asks its questions afterwards. The consider way and the choices way carry this guidance. considered.via says what the operator was shown. No separate field records it.

4. The tool does not run observables¶

adr does not execute run entries. The agent runs them during the handover, or while iterating on the work (§3). A command runner in the tool can be decided later, once there is evidence of how observables are written.

Consequences¶

Positive¶

A decision can say how anyone, human or agent, would see it holding, in whatever form suits the work.
A consideration made after a demonstration differs, in its via, from one made after reading.

Negative¶

Nothing enforces that an observable exists, or that it works.
A loose field is harder to use mechanically later, for a runner or a report.

Neutral¶

Imported records carry no observables until someone adds them, which §2 allows.
enacted stays as it is. It is the observable end of a cut or retire.

Alternatives Considered¶

A fixed shape: see plus an optional run. Rejected by the operator as too narrow for the variety of work.
Required on add and change, with a lint warning. Rejected in favour of optional everywhere. The agent asks when drafting (§3), and the field itself stays optional.
A seen list on considered. Rejected: via already says what the operator was shown.
adr observe N running a decision's commands. Deferred until observables have been written in practice.

Corrections¶

Appended 2026-09-27. The entry was first made in place after acceptance and moved here so the accepted text above stays as it was. It does not change what was decided.

Demonstrating observables. The consider way carries this guidance, and routes a batch of questions through the choices way. The accepted text said the consider way and the choices way both carry it; the choices way does not mention observables.