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. When 2-4 decisions at the same boundary are independent of each other and their prerequisites are settled, you may ask them together with `questions` instead of `question`. Each entry carries its own `question`, `context`, `options`, `allowMultiple`, and `allowFreeform`. Never batch a decision whose options depend on another answer; ask it in a later call once that answer is known. ### 5) Commit the decision After response: - restate the decision in plain language - state what will be done next - proceed with implementation ### 6) Re-open only on new ambiguity Ask again only if materially new uncertainty appears. Avoid repetitive confirmation loops. ## Anti-overasking guardrails (required) Apply a strict question budget per decision boundary: - **Max 1** `ask_user` call per decision boundary in normal cases. - **Max 2** `ask_user` calls for the same boundary when first response is unclear/cancelled. - Never ask the same trade-off again without new evidence. Escalation ladder: 1. **Attempt 1:** structured options + concise context. 2. **Attempt 2 (only if needed):** narrower question with agent recommendation and explicit choices: - `Proceed with recommended option` - `Choose another option` (freeform) - `Stop for now` After attempt 2: - If boundary is `high_stakes` or `both`: **stop and mark blocked**. Do not keep asking. - If boundary is `ambiguous` only and user says “your call” or equivalent: proceed with the most reversible default and state assumptions explicitly. ## `ask_user` payload quality standard ### Question quality Use: - “Which option should we adopt for X?” - “Do you want A (fast) or B (safer) for Y?” Avoid: - broad/open prompts with no decision boundary - multiple unrelated decisions in one question - questions that should be answered by reading code/docs first ### Option quality Options must be: - mutually understandable - short and outcome-oriented - explicit on trade-offs Good options include a short description when trade-offs are non-obvious. ## Recommended patterns ### Single-select architecture decision ```json { "question": "Which caching strategy should we use for the first release?", "context": "Current API has p95 latency issues. Redis is fastest but adds infra complexity; in-memory cache is simpler but not shared across instances.", "options": [ { "title": "In-memory cache", "description": "Simpler rollout, weaker horizontal consistency" }, { "title": "Redis cache", "description": "Better consistency and scalability, more ops overhead" } ], "allowMultiple": false, "allowFreeform": true } ``` ### Multi-select when decisions are independent ```json { "question": "Select the first-wave hardening items to implement now.", "context": "We can ship quickly with baseline controls, then add targeted hardening. Budget is limited to 1-2 days.", "options": [ { "title": "Rate limiting" }, { "title": "Audit logging" }, { "title": "Input schema validation" }, { "title": "Secrets rotation" } ], "allowMultiple": true, "allowFreeform": true } ``` ### Independent decisions at one checkpoint ```json { "questions": [ { "question": "Which logging backend should the service use?", "context": "Both integrate with the existing middleware; only the hosted option needs a new vendor contract.", "options": [ { "title": "Self-hosted Loki", "description": "No new vendor, more ops work" }, { "title": "Hosted Datadog", "description": "Fastest setup, recurring cost" } ] }, { "question": "Should the first release include the admin dashboard?", "options": [{ "title": "Include it" }, { "title": "Defer it" }], "allowFreeform": false } ] } ``` ## Anti-patterns - Asking `ask_user` without first gathering context - Using it for trivial formatting choices - Forcing options when freeform is clearly better - Asking the same question repeatedly without new information - Batching dependent decisions in `questions`, or using a batch to dodge the one-decision-per-question rule - Proceeding with high-stakes implementation after unclear/cancelled answer ## If user cancels or answer is unclear Pause execution and explain what is blocked. Use at most one narrower follow-up `ask_user` question (attempt 2). After that, do not continue asking in a loop: - for high-stakes decisions: remain blocked until explicit decision - for ambiguity-only decisions: proceed only if user delegated the choice ("your call") ## Additional reference For full trigger matrix, UX conventions, and extension interaction details, read: - `references/ask-user-skill-extension-spec.md`