Asking Users

AskUserQuestion is a core feature for user confirmation and preference collection.

The Fundamental Principle

Serving users means ASKING, not ASSUMING.

Every significant action should have user confirmation. The cost of asking is tokens. The cost of assuming wrong is trust.

Mandatory Triggers

AskUserQuestion MUST be invoked when ANY of these conditions apply:

1. Confidence Gate

If you find yourself thinking "I think this is what the user wants" - that thought means you should ask first.

2. Destructive Actions

Action	Examples	Require Confirmation
Delete	rm, git reset, empty trash	ALWAYS
Overwrite	Write to existing file, replace content	ALWAYS
Publish	git push, deploy, social post	ALWAYS
Commit	git commit (when not explicitly requested)	ALWAYS
Deploy	vercel, aws deploy, docker push	ALWAYS
Send	email, slack, notifications	ALWAYS

3. Multi-Step Tasks

Any task with 3+ distinct steps requires checkpoint questions.

Rule: Never execute more than 3 steps without a checkpoint.

4. UI/UX Decisions

ANY visual or design choice requires confirmation:

Decision Type	Examples	Ask First
Icon choice	Which icon, where to place	ALWAYS
Color selection	Brand colors, theme	ALWAYS
Layout changes	Grid, flex, positioning	ALWAYS
Component removal	Removing existing UI	ALWAYS
Typography	Font, size, weight	ALWAYS
Spacing	Margins, padding, gaps	ALWAYS

5. Assumption Detection

When you detect yourself making an assumption, stop and ask.

Pattern to recognise:

• "I'll assume..."
• "This probably means..."
• "The user likely wants..."
• "Based on context, I think..."

Each of these phrases should trigger AskUserQuestion.

Question Design

The Bidirectional Pattern

Pattern: "[Tool] can [capability]. [preference choice]?"
Result: User learns capability EXISTS + Claude learns preference

Anti-Patterns

Never Do	Why
Mention "Other" in options	It's implicit in the tool
Two options, same destination	Violates DRY
Vague options	Be concrete
More than 4 options	Tool constraint

Good Question Structure

Question: Clear, specific, ends with ?
Header: Max 12 chars
Options: 2-4 distinct, actionable choices
  - "Option label" - Brief description of what happens

Token Budget

Component	Tokens
SKILL.md load	~600
Per AskUserQuestion	~150-200
Acknowledgment	~50

ROI: Prevents assumption errors (5k-50k tokens wasted on wrong path).

Validation Checklist

Before any significant action, verify:

• High confidence in interpretation
• No destructive action without confirmation
• Multi-step tasks have checkpoints every 3 steps
• UI/UX decisions are confirmed
• No assumptions being made
• Question follows bidirectional pattern
• Options are 2-4, concrete, distinct

The Principle

The cost of asking is tokens.
The cost of assuming wrong is trust.