framing-decisions

Route every decision you'd put to the user through this protocol: one decision at a time, explained, through the AskUserQuestion tool. It overrides any default that batches unrelated decisions into a single call.

The option set is the failure surface. A menu can be well-explained, well-recommended, and still worthless because the right answer was never on it — so most of this protocol runs before the options exist.

The protocol

Work the open decisions in priority order, one pass per decision:

1. One decision per call. Send AskUserQuestion carrying that decision, then wait for the answer before composing the next. Questions that are facets of one decision may share a call; separate decisions get separate calls. This governs unstructured conversation, where nothing orders the decisions against each other and a batch silently mixes decisions that depend on one another. Inside a grilling session it does not apply: a frontier is separate-but-related by construction — every prerequisite decision settled in an earlier round, and any question still waiting on a fact being gathered held back to a later one — so grilling schedules the round and this protocol builds each question in it. What still goes alone, there as here, is a question that could reframe its neighbours — ontological, premise-fragile, or wide fan-out; ask it first, wait, then re-derive the rest.
2. Answer it as the expert first. Before drafting any option, solve the decision yourself as a senior practitioner of the discipline it belongs to — the domain's own developer, the process engineer, the UX designer, the statistician — reasoning from the problem rather than from the options you were about to offer. On a hard, high-stakes, or multi-session call, spend real thought here, and dispatch a domain-expert subagent where the field is outside your strength; a menu built cheaply here costs weeks of building the wrong thing. This answer is your recommendation unless you find a stated reason to depart from it.
3. Audit the menu against it. Check the option set, and rewrite it when a check fails:
   • The expert answer is on the menu. If it isn't, the menu is wrong — fix the options, not the caveats.
   • Run the pre-flight. Name, in one word, the variable the options vary — four token units, four similarity definitions, whatever it is — then ask whether that variable is the decision or a symptom of it. At least one option must not be a value of that variable: it must dissolve the question, compose across the others, or move up a layer (the token-units question was really about the medium, one level up). For each option, state what changes downstream; two options with identical downstream consequences are one option written twice. Detection, not prevention: some layer errors need domain insight you won't have until the human pushes back — being wrong and re-posing fast is the expected path, not a failure.
   • The parent is settled. A question that allocates the contents of something — which result goes in this paper, which work lands in this phase, which feature ships in v1 — is only answerable once that container is defined. Name the parent decision and where it was settled: a file and a date, or a message you can point at. If you can't produce one, the parent is the question — ask it instead and drop this one. grilling enforces this by round and calls it the frontier; outside a grilling session nothing enforces it, which is precisely where the ordering error goes unnoticed.
   • Mechanisms compose. When the options are mechanisms rather than values, a pipeline that runs several of them in a chosen order is a required candidate — and the one to recommend, not omit, when the mechanisms are complementary rather than exclusive: "A proposes, B adjudicates," offered as its own option with the ordering you'd pick named.
   • A losing option keeps a job — if it lost on merit. Before cutting a mechanism the composed option didn't need at the top, ask what it would still be good for downstream — validation, a subordinate signal, a fallback — and give it that role instead. A mechanism rejected because it's unsafe, wrong, or refuted gets no such role: let it die, don't let it back in downstream as "validation" or a fallback.
   • Ontology gets constraints, not menus. When the decision is what something is — its unit, its medium, its atom, its state — finished-answer options encode a prior the domain expert may not hold; name which level the question is actually at first (the medium a claim runs on is not the subject it's about — a mismatch there loses whole rounds unnoticed). Offer candidate constraints or invariants instead of answers, plus an explicit option to name one none of them captures.
   • The premise is named. State in one line the assumption every option rests on, so the user can reject the frame instead of only the choices. This is where the out-of-the-box answer comes from.
4. Explain first. Before the options, say in plain language what is being decided and why it matters — the stake, the tradeoff, what turns on it. Give enough that the user can choose from the question alone, without rereading the analysis above it.
5. Options with a steer. Offer concrete options, never "what would you like to do?". Put your single recommendation first, marked (Recommended), and make each option's description state what it means and what it costs.
6. Defer where fan-out is high. On a decision whose answer is expensive to unwind later, "defer — here is the probe that would settle it, and what the probe costs" is itself a legal option, not a fallback you reach for only once stuck. But when the reason for deferring is that some set isn't enumerated yet — "a criterion over an unknown set is not a criterion" — spend one round on what generates the set before you record the deferral. The generator is usually already in hand, and finding it collapses the deferral into a one-line rule.
7. Adapt on the answer. After each answer, re-derive what is still open: the next question may shift on what they just said, and some planned questions fall away. Compose the next one fresh rather than reading down a fixed list. Check first that the answer answers your question — a selection matching no option you offered, or text replying to something you didn't ask, is a harness fault rather than a preference. Re-pose the question verbatim instead of interpreting it.

An override is evidence — capture it. When the answer is anything but the option you recommended — a different pick, a rewritten option, an addition where you offered a choice, a rejected frame — your model of what they want was measurably wrong, and that is the most informative thing that happens in this protocol. Log it before acting on it:

~/.claude/skills/bin/skill-learnings-log '{"type":"preference","key":"<kebab-slug>","insight":"<what you would have done, what they chose instead, and their reason if given>","confidence":8,"source":"user-stated"}'

Overrides only, and only where the answer would change your default next time on a question not yet asked — a store full of one-off situational choices buries the few that generalise. Agreement with your recommendation teaches nothing and is not logged. Never let logging delay the work or become something you ask about. Store rules, and the line between this and a memory file, are in COMPOUNDING.md.

Think long, write short. The thinking in steps 2 and 3 runs deep; what reaches the screen stays lean — a few sentences of explanation, one line for the premise, one line per option. Cut prose that restates the options, recaps analysis the user just read, or pads the recommendation.

Frame rejection means go up, not re-draft. When the answer rejects the premise rather than the options — "I'm not sure X is the right frame", or an answer that adds to the menu instead of picking from it — a better menu at the same layer is never the repair. Re-ask the parent question the rejection just exposed. Treat an addition as settled: if they said "and" where you offered "or", the composition is the answer, and every still-open question gets re-derived against it rather than asked as drafted.

Escalation means re-solve, not reformat. Being asked by name to invoke this skill mid-conversation means the last answer was too thin, not merely the wrong shape — return to step 2 and spend real effort there before rebuilding the menu.

Done when no decision is left that would change what you do without guessing — a deferral with its probe now running counts as answered. Then stop asking and act.