ADR-0101 — Open decisions carry options + a recommendation, in decision-bearing authoring
- Sections
- 5
- Format
- Markdown
- Order
- 137 / 156
Context
When an authoring agent hits a genuine fork — a behavioral choice the artifact cannot settle on its
own — the framework's handling is uneven. The review template does it well: ## Open decisions
(ADR-0089) — 2–4 comparable options, the case FOR and
AGAINST, a recommendation + why, what it blocks. The spec authoring path is thinner: write-spec
rule 7 routes ambiguity to a bare ## Open questions list — no options, no recommendation. So whether
the human receives a decidable fork or a vague question depends on which artifact is in hand. The
good pattern already exists; it just isn't standard. (From the session deliberation; RFC-authoring-open-decisions.)
Decision
-
A decision-bearing authoring artifact surfaces each genuine fork as options + a recommendation, in the ADR-0089 shape — never a bare question, never a silent guess. The spec's existing
## Open questionssection (frozen by ADR-0058, checked by C006) is filled with options + a recommendation — not renamed: the decision in one line · 2–4 options with FOR/AGAINST · a recommendation + a brief why · what it blocks. A real "don't know yet" is a one-option decision whose recommendation is "find out how." This is a content-discipline change, not a format change — the section name, the frozen list, and C006 are untouched. Level: convention. -
Runner-honest interaction. Where the runner supports an interactive prompt (e.g. Claude Code's question UI), the agent asks and proceeds on the answer; where it does not (a file-only worker, another harness, a human), it records the same
## Open decisionsfor the owner. The principle (options + a lean, never a guess) is runner-agnostic; the interactive mechanism is a Claude-Code affordance that does not travel (ADR-0098) — additive in the suspec-agents layer, never required of the format. Level: convention. -
Genuine forks only (anti-ceremony). This fires on a behavioral choice that changes the artifact's meaning, not on every micro-wording choice. An empty
## Open decisionsis correct when there is no real fork; padding it is the ceremony overhead (suspec-works#72) this must not add. Level: convention. -
Scope: where the artifact decides. The convention binds artifacts that make a behavioral decision — the spec (primary) and the RFC (which already carries Alternatives + a decision requested). Observation/intent stances are exempt: an audit records present state and recommends only in prose, a PRD states intent, research surveys without deciding. Forcing an options-block on them would manufacture decisions the stance forbids. Level: convention.
Consequences
- No
checks.yamlrule, no contract bump — a convention, consistent with the honesty framework (ADR-0063). - Reaffirms ADR-0089 (the open-decisions shape) and ADR-0098's no-travel boundary (interactive is additive, not required).
- The spec gains a decidable fork where it had a vague list; the human gets a lean, not a quiz.
- No format change. The
## Open questionsheading is the frozen ADR-0058 section and the C006 target; both are untouched. Existing specs stay valid — only the guidance on how to fill the section changes.
Propagation
The kit spec template (upgrade the ## Open questions guidance to options + a recommendation —
no rename), the write-spec guide (rule 7), and a note that write-rfc already complies and
audit/PRD/research are exempt. suspec-agents worker definitions may wire the interactive prompt
(Claude-Code only, marked non-portable). No review-packet or spec format break.
Affected obligations / constraints
Starter kit: Set up a workspace