always-ask-on-unresolved
Always Ask on Any Unresolved Item — Mandatory AskUserQuestion Usage
Section titled “Always Ask on Any Unresolved Item — Mandatory AskUserQuestion Usage”You MUST invoke AskUserQuestion for ANY unresolved item. Prose “A or B?”, bulleted choice lists, and “Pick one of:” blocks are all violations — STOP and call AskUserQuestion instead. The seven triggers:
- Any prose question you’d otherwise phrase to the user (yes/no, “should I…?”, “can I…?”, “ready to…?”) — unless the answer is already on record (see exceptions)
- Any unresolved item in a plan before proceeding (
TBD,TODO,??markers, phase conflicts) - Any unresolved item in a report before submitting it as final
- Any ambiguity discovered mid-implementation not covered by the prior plan/answer
- Any default value or policy choice not explicitly handed to you (thresholds, fallbacks, retention)
- Any deletion, overwrite, or destructive action with non-trivial blast radius
- Any skill needing a multi-option decision — skill bodies MUST call
AskUserQuestion, no “emitted prose” exemption
When in doubt, ask: asking is cheap, assuming is expensive.
Plan / report deliverables: before finalizing either, scan for unresolved markers (TBD, TODO, ???, pending, unclear), batch them into AskUserQuestion (max 4 per call), and mark ready only once all resolve. An “Unresolved questions” section survives ONLY on explicit user deferral.
If AskUserQuestion is deferred
Section titled “If AskUserQuestion is deferred”AskUserQuestion is auto-deferred in long-context sessions (its NAME appears in the deferred-tools reminder; schema is NOT loaded). Direct call fails with InputValidationError. Required first action:
ToolSearch(query="select:AskUserQuestion", max_results=1)Deferral is NEVER a justification for a prose fallback — the schema is one ToolSearch call away. Load it, then invoke AskUserQuestion with the batched options as originally intended. The enumerated forbidden phrasings (“AskUserQuestion isn’t available… I’ll ask in prose”, prose Q1/Q2/Q3 lists, “Pick one of:” blocks) and the preload-hook detail: docs/decision-discipline-examples.md § “the tool is deferred”.
When NOT to use
Section titled “When NOT to use”Plan-approval flows use ExitPlanMode, not this tool. Factual yes/no questions and pure-acknowledgment replies stay as prose.
Narrow exceptions (when NOT to ask)
Section titled “Narrow exceptions (when NOT to ask)”Direct command this turn · a standing approval already on record — a config flag, a decision-authority rule, or a hook frame delivering one — is answered, not unresolved · reporting results (not deciding) · pure factual lookup · plan approval (use ExitPlanMode) · re-asking decisions already answered this session (structured artifact OR unambiguous chat prose). A NEW decision not covered by the prior answer triggers a fresh AskUserQuestion; if you’d need to guess between two interpretations, ask.
Full details
Section titled “Full details”Enumerated triggers, the plan/report protocol, and the narrow-exception table: docs/always-ask-on-unresolved.md. Source: ~/.claude/CLAUDE.md #2.