edlsh/pi-ask-user/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 or displayMode in ask-user.json; 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 or contextExpanded in ask-user.json; 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. A top-level question sent with questions is only a heading, never asked. 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

{
  "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

{
  "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

{
  "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