Presenting Choices¶
Source: hooks/ways/meta/choices/choices.md
Frontmatter
| Field | Value |
|---|---|
description |
deciding whether a call goes to the operator or is settled by the agent, the waterline for technical calls that set direction, and presenting genuine decisions as explicit choices rather than burying options in prose or deciding silently |
vocabulary |
choice option decision present ask user select alternatives branch point recommend tradeoff prefer fork pick which clarify rubber-stamping over-asking hedging fatigue pending waterline worth asking escalate library framework dependency reversible settle overrule |
pattern |
which (one|option|approach)|ask the user|let.{0,15}decide|how (should|do) (we|you|i)|waiting on (me|for me)|decisions? (for|from) me|need from me|should i ask |
refire |
0.15 |
scope |
agent, subagent |
A real branch point is a set of distinct options whose answer changes what you do next. When you hit one, present it as an explicit choice. Burying it in a paragraph makes the human parse it; picking silently makes them discover it from the result.
Ask in your reply first, laid out so the human can answer in a few words. When this session listens on attend, the human can answer there while the work continues. The harness also has a question tool (AskUserQuestion), with structured options, short headers, a recommended default and one-line tradeoffs. The tool holds the turn open until the human answers, so for a single choice use it only when the decision blocks the work, meaning each turn built past it would make it more costly to undo. A series of calls above the waterline, and a decision record's probes, go through the tool whenever the operator is present (choices/interview, how to ask). Each of these surfaces costs the human less than a wall of prose that ends in "let me know how you'd like to proceed", and less than a guess they have to undo.
The waterline¶
You own technical calls by default and ground each one in evidence. Every call has some effect on the work, so the test for sending one to the operator is what it sets. Choosing one library, framework, protocol, storage engine or language over another sits at the line and goes to the operator: it is costly to reverse once code builds on it, and the operator may want to research the options before committing. Which function of the chosen library to call sits below it.
Ask the operator about:
- a one-way door, or a call many later steps depend on
- a persisted format or wire contract that others read
- anything users type or configure, such as a setting's name or default, or a command's name
- a default users will feel, such as a key binding or a feature that is on by default
- a new binary, service or process boundary
- a trust surface, such as an open port or reading other users' or sessions' data
- a support promise, such as a minimum version or the supported platforms
- building on an undocumented internal where a documented interface exists
- a dependency's licence, or anything that spends money or quota
- a semantic rule other code will rely on, or a change of scope
- giving up something the operator said they wanted, or shutting out an approach they might still want
Settle and say what you chose for: a call that is cheap to reverse or local to one place; internal modules, functions and data structures; test shape and fixture names; a judgement call inside a decided feature, recorded where it is visible; re-pinning a baseline after an intended change, with the delta explained; a call the evidence decides.
Some calls sit on the line, and a qualifier decides:
- A new dependency is above it when it ships at runtime, and below it when it is for development or tests only.
- A setting's name is above it once a release has shipped it, and below it while it exists only on an unmerged branch.
- The wording of a user-facing message is below it. Removing information users relied on is above it.
The lists are examples drawn from a wider test: how costly a call is to reverse, and whether the operator would want a say in it. Judge a call they don't name by that test, and judge a listed call by the situation in front of you: a listed kind that is trivial here may sit below the line, and an unlisted call that sets direction sits above it. Say which way you read it.
When more calls qualify than one batch holds, rank them by reversal cost, ask about the top few, and settle the rest with each lean stated so the operator can overrule any of them. A series of these is an interview (choices/interview).
When to surface a choice¶
| Situation | Surface it? |
|---|---|
| Distinct options, the call is above the waterline, no obvious default | Yes — present the choice |
| Multiple independent decisions stacked up at once | Yes — a few focused questions beats a prose dump |
| One option is clearly right given the context | No — pick it, name it, proceed (say what you chose and why) |
| A fact you can verify in the code or docs yourself | No — go look; don't outsource lookups |
| "Is my plan ready / should I proceed?" | No — that's not a choice, it's hedging |
How to present well¶
- Lead with a recommendation. Put the option you'd pick first, mark it, and give the evidence for it. A choice with no point of view burdens the human.
- Make options genuinely distinct. If two collapse to the same outcome, it's one option. State the tradeoff along with the label.
- Keep it small. Two to four options per question, a handful of questions at most. The goal is calibration.
- Carry the context in each question. Say what was built or decided and what the answer changes, so the human can answer without opening the PR, file or record. "Merge #588?" sends them to look; "#588 makes CI run on records-only PRs; merge it?" does not.
- Batch what is pending. When several decisions have stacked up, or the human asks what you are waiting on, ask them together, one question each.
- Shape the interaction to the decision, and vary it. A decision whose options each fit in a line suits a numbered list in the reply, which the human answers in a few words. A complex one is a flow: lay out the argument in prose or a doc, then ask the questions it leaves open, which may differ from the ones you started with. One step of the flow can be the work itself, where that is possible: run it and show what it does (the output, a screenshot, a page to try) before asking, so the human decides from what they saw. The same interaction every time fatigues the human as surely as a wall of prose does.
- Don't ask what you've been told. If the human already decided, act on it.
The bar is a genuine fork. Over-asking trains the human to rubber-stamp, which defeats the point — the same way a linter that nags on non-defects trains its reader to ignore it. core.md sets the bar for when to ask.
See Also¶
- choices/interview(meta) — child: a series of directional decisions, each with a brief, the case for and against, and a lean from evidence
- adr/consider(documentation) — the operator's check of a drafted decision record
- trust/autonomy(meta) — when to act without asking vs. check in first
- delivery/implement(softwaredev) — defend a plan, then invite challenge