ask-user

Ask User Decision Gate

Use this skill to force explicit user alignment before consequential decisions.

This skill is about decision control, not general chit-chat.

Non-negotiable rule

Invoke ask_user before proceeding when any of the following is true:

1. The next step changes architecture, schema, API contracts, deployment strategy, or security posture.
2. The work is costly to undo (large refactor, migration, destructive edit, production-facing behavior change).
3. Requirements, constraints, or success criteria are unclear, conflicting, or missing.
4. Multiple valid options exist and the trade-off is preference-dependent.
5. You are about to assume something that can materially change implementation.

Do not skip this gate unless the user has already provided a clear, explicit decision for the exact trade-off.

Agent Protocol Handshake (required)

Follow this handshake in order.

1) Detect boundary

Classify the current step as:

• high_stakes
• ambiguous
• both
• clear (no gate needed)

If classification is not clear, continue.

2) Gather evidence first

Before asking, gather context from available tools (read, bash, exa, ref, etc.). Do not ask the user to decide blind.

3) Synthesize context

Prepare a short neutral summary (3-7 bullets or short paragraph) covering:

• current state
• key constraints
• trade-offs
• recommendation (if any)

4) Ask one focused question

Call ask_user with one decision at a time:

• question: concrete decision prompt
• context: synthesized summary
• options: 2-5 clear choices when possible
• allowMultiple: false unless independent selections are genuinely needed
• allowFreeform: usually true
• displayMode (optional): "overlay" (default) or "inline". Use "inline" when preceding assistant context (summary, trade-offs, recommendation) is essential to the decision and should remain visible — overlays cover the conversation underneath. The user may set a personal default via the PI_ASK_USER_DISPLAY_MODE environment variable; only pass this when you intentionally want to override it for one call.
• contextExpanded (optional): true opens oversized context fully expanded instead of collapsed behind a one-line summary. The user may set a personal default via PI_ASK_USER_CONTEXT_EXPANDED; only pass this when the context is the evidence the user needs to weigh the options.