claude/docs/superpowers/specs/2026-09-16-ask-dont-guess-design.md

Ask, don't guess: clarification doctrine for the orchestrators

Date: 2026-09-16. Branch: feature/ask-dont-guess. Status: draft for user review.

Problem

The orchestrators (/ship-feature, /feat, /bugfix, /hotfix, /init-project) settle choices the user never made. Reported symptom: "add a share icon" ships with the icon wherever the executor put it; nobody asked left or right.

Two causes, both written in the doctrine:

1. lib/contract-interview.md STEP 2 asks a question only when a testable outcome, a scope, or a non-contradictory constraint is missing. A request can pass all three and still leave every visible choice open. Taste is invisible to the trigger, so raising the 3-question cap would change nothing.
2. When an executor halts with NEED-DECISION, skills/feat/SKILL.md:153 and skills/bugfix/SKILL.md:165 instruct the orchestrator to "make the decision HERE", twice, before escalating. The question reaches the user after two guesses.

The parent rule both inherit is CLAUDE.global.md:51: "One question upfront if needed — don't interrupt mid-task."

Decisions taken with the user (2026-09-15/16)

• The global rule changes, for all work, skill or not. /hotfix included.
• Three classes of open choice trigger a question: VISIBLE (placement, label, wording, color, order, click behavior), PUBLIC NAME (command, flag, endpoint, env var, file the user reads), SCOPE (should X change too, X unnamed in the request). Class 4, internal technical choices with no observable effect, never triggers one.
• Questions are asked when they arise, mid-task included, batched when possible.

Design

1. Parent rule, CLAUDE.global.md

Line 51 becomes:

- Ask rather than guess. A choice visible in the result (placement,
  wording, order, behavior), a name that becomes public (command, flag,
  endpoint, file), or a scope the request does not settle → ask, even
  mid-task. Batch what can be batched. Internal technical choices with
  no observable effect stay yours.
  *Exception: skill-mandated gates and checkpoints (orchestrator
  validation gates, approval gates, darwin checkpoints) always fire.*

The exception line is kept as is.

The rule "Bug received → fix directly: check logs, find root cause, resolve autonomously." gains "; a visible choice in the fix still gets asked" so the two lines do not contradict each other. link.sh:20 symlinks this file to ~/.claude/CLAUDE.md; no other copy exists.

2. Shared trigger, lib/contract-interview.md STEP 2

STEP 2 is renamed CLARIFY and split into two passes. Pass A keeps the three existing gap checks and runs at contract time, against the request. Pass B is the open-choice sweep: defined here, run once per flow at the PLAN step (section 3), against the plan just written, because that is where a visible choice becomes concrete. Replacement text:

## STEP 2 — CLARIFY (ask, never guess)

Two passes, both in the main loop, both may talk to the human.

**Pass A — gaps.** Run here, against the request. Ask if one of these is
missing AND not derivable from the repo:
- a testable expected outcome
- an unambiguous scope (what is allowed to change)
- non-contradictory constraints

**Pass B — open choices.** Defined here, run ONCE at the flow's PLAN step
(see "Where pass B fires"), against the plan just written — that is
where choices become concrete. Enumerate every choice the run will
settle that the request leaves open; keep those in these classes:
1. VISIBLE — the user would see it in the result: placement, label,
   wording, color, order, what a click does.
2. PUBLIC NAME — a name that outlives the run: command, flag, endpoint,
   env var, a file the human will read.
3. SCOPE — "should X change too?", where the request does not name X.

NEVER ask class 4 — internal technical choices with no observable
effect (function decomposition, data shape, local naming, layout inside
an already-scoped zone). Those are delegated; asking them is the noise
that makes classes 1-3 ignorable. Never ask what the repo or the
request already answers — verify paths/APIs/behavior yourself first.

No question cap. Each pass asks what it finds, in ONE batch. A request
that leaves nothing open goes through silently. More than 5 open
choices in pass B = the request is under-specified: list them, say so,
stop — do not fire a questionnaire. "You decide" / "peu importe" is an
answer: record it as `A: delegated — <default taken>` and never re-ask.

Pass B answers land in the contract's CLARIFICATIONS marked
`[gated <YYYY-MM-DD>]` — the contract is already on disk by then.

Two new sections follow STEP 4 in the same file:

## MID-RUN CLARIFICATION (the channel executors halt into)

An executor cannot talk to the human. It halts with `NEED-DECISION`,
the exact question, the options it sees, and a `CLASS:` tag (visible |
public-name | scope | internal). `/hotfix`: the hotfixer keeps
`DONE | BLOCKED`; a BLOCKED carrying the tag follows the same routing
instead of escalating to `/bugfix`. The orchestrator re-reads the
class — the tag is a hint, not a verdict — then routes:
- visible / public-name / scope → ASK THE HUMAN, verbatim question and
  options. Never decide these yourself, never spend a round-trip
  guessing.
- internal → decide here, note the decision, re-dispatch. The only case
  the orchestrator settles alone; max 2 such round-trips → escalate.

Every answer, human or orchestrator, appends to the contract's
CLARIFICATIONS marked `[gated <YYYY-MM-DD>]` — the same micro-gate as
scope enrichment — and to the plan handed to the FRESH re-dispatched
executor, which reads the decision from disk, never from a transcript.

## HOW TO ASK (LRN-102)

The harness reliably renders only the turn's FINAL text; text printed
before a tool call may be swallowed. So:
- up to 4 questions → one `AskUserQuestion` call; option descriptions
  carry the context; print nothing the user needs before the call.
- more than 4, or a list handed back for re-specification → plain
  text, end the turn.

The per-flow weight table row for hotfix changes from "Zero questions ever" to "Pass A silent autofill. Pass B runs at LOCATE against the 1-2 target files' visible effect; a typo fix asks nothing."

3. Where pass B fires, per flow

Flow	Pass B runs at	Against
feat	STEP 1 PLAN, before 1b CHALLENGE	the PLAN checklist
bugfix	STEP 3 FIX PLAN	the FIX PLAN
hotfix	STEP 1 LOCATE	the 1-2 target files' visible effect
ship-feature	STEP 2 PLAN, after the brainstorm	the plan, minus what the brainstorm already settled (in CLARIFICATIONS)
init-project	STEP 3 DESIGN, before VALIDATION GATE #1	the DESIGN, minus what the interview and brainstorm settled
onboard	unchanged	its STEP 3 interview already asks scope in one block; the global rule covers leftovers

Each listed step gains one line: "Run pass B of $HOME/.claude/lib/contract-interview.md against this plan; ask the batch before continuing."

4. Per-flow edits

• skills/feat/SKILL.md: STEP 1's "If the approach is ambiguous: ask the user ONE focused question BEFORE dispatching — never after (the executor cannot relay questions)" is replaced by the pass B line. STEP 3's NEED-DECISION handling is replaced by a pointer to MID-RUN CLARIFICATION. STEP 1b's "surfacing any deferred BLOCKER via STEP 1's one-question gate" is repointed to the pass B batch.
• skills/bugfix/SKILL.md: STEP 3 gains the pass B line; STEP 5's NEED-DECISION handling is replaced by the pointer. The RULES line "re-dispatched FRESH on every round-trip (NEED-DECISION, …)" stays true.
• skills/hotfix/SKILL.md: STEP 1 gains the pass B line. STEP 1.7's "zero questions ever" becomes "pass A silent autofill; pass B was asked at STEP 1". The hotfixer keeps DONE | BLOCKED and its revert-not-loop identity; STEP 4 relays a tagged BLOCKED as a question instead of escalating to /bugfix.
• skills/ship-feature/SKILL.md: STEP 2 PLAN gains the pass B line.
• skills/init-project/SKILL.md: line 62's "No new questions (the interview already asked)" becomes "Pass A is covered by the interview; pass B runs at STEP 3 against the DESIGN". STEP 3 gains the pass B line.
• agents/interviewer.md: the FAILURE MODES rows and the 2-round budget keep working for gaps. A class 1-3 item still open after round 2 gets ONE more targeted question; it never lands in OPEN DECISIONS as (assumed). The DO NOT entry "Exceed the 2-round budget" gains "except the one targeted class 1-3 question".
• agents/feater.md, agents/bugfixer.md: the halt trigger "A plan hole or an open choice (naming, data shape, API surface, dependency)" gains "a user-visible choice (placement, wording, behavior)". The NOTES grammar for NEED-DECISION gains CLASS: visible | public-name | scope | internal.
• agents/hotfixer.md: the NOTES grammar for BLOCKED gains the same CLASS: tag when the blocker is an open choice.

5. Locks and tests

lib/tests/contract-verifier.test.sh: drop "silent when complete" "ZERO questions" and "question budget" "max 3 questions". Add locks on: "goes through silently", "No question cap", "PUBLIC NAME", "NEVER ask class 4", "More than 5 open choices", "delegated —", "## MID-RUN CLARIFICATION", "CLASS:", "## HOW TO ASK".

lib/tests/loops-light.test.sh:84: "hotfix zero questions" "questions ever" becomes "hotfix pass B at locate" "pass B".

lib/tests/gates.test.sh locks on contract-interview.md (oracle doctrine) are untouched; the ORACLES section does not move.

Behavioral check, run once by hand after the edits, in a fixture repo: /feat "add a share icon to the header" must ask placement before dispatching; /feat "add a share icon at the right end of the header, label Share, opens the native share sheet" must ask nothing.

6. Out of scope

• README.md, USAGE.md, ARCHITECTURE.md: none mentions the question doctrine (grep 2026-09-16). A /doc pass after merge covers any flow description that drifts.
• CHANGELOG.md entry and registries (a BDR superseding the "one question upfront" rule) happen at the CAPITALIZE step, not in this spec.
• TODO.md line 199 (C2 self-contradiction audit of CLAUDE.global.md) stays open; this spec fixes only the contradiction it exposes.

7. Risks

• Chattiness. Three classes, a mid-run channel, no cap. The class 4 exclusion and the over-5 guard are the two brakes. Watch in real use; LRN-047 records that a frequent ignored nag is itself a risk.
• /hotfix identity. Its value is speed and silence. Pass B at LOCATE adds one possible batch before touching anything. If it fires on most hotfixes, the class definitions are too wide, not the flow.
• Executor mis-tagging. A class 4 tagged as visible offloads a decision to the user. The orchestrator re-reads the class; the tag is a hint.