Skip to content
Skills Library
AI & agents · Planning

ask-user

/ask-user

You MUST use this before high-stakes architectural decisions, irreversible changes, or when requirements are ambiguous. Runs a decision handshake with the ask_user tool: summarize context, present structured options, collect explicit user choice, then proceed.

Author
edlsh ↗
Repository
pi-ask-user ↗
Licence
MIT
Last repository change
19.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 19.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

You MUST use this before high-stakes architectural decisions, irreversible changes, or when requirements are ambiguous. Runs a decision handshake with the ask_user tool: summarize context, present structured options, collect explicit user choice, then proceed.

Original author description

You MUST use this before high-stakes architectural decisions, irreversible changes, or when requirements are ambiguous. Runs a decision handshake with the ask_user tool: summarize context, present structured options, collect explicit user choice, then proceed.

How it works

  1. Non-negotiable rule
  2. Agent Protocol Handshake (required)
  3. Anti-overasking guardrails (required)
  4. askuser payload quality standard
  5. Recommended patterns
  6. Anti-patterns
  7. If user cancels or answer is unclear
  8. Additional reference
Original SKILL.md headings · 184 lines, 1,034 words
SKILL.md preview
---
name: ask-user
description: "You MUST use this before high-stakes architectural decisions, irreversible changes, or when requirements are ambiguous. Runs a decision handshake with the ask_user tool: summarize context, present structured options, collect explicit user choice, then proceed."
metadata:
  short-description: Decision gate for ambiguity and high-stakes choices
---

# 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

```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`
Files in this package (2)
  • SKILL.md 7 KB
  • references/ask-user-skill-extension-spec.md 4 KB

Versions

The database has no other skills named ask-user.

Database snapshot: 13.11.2026 · package version b60b2a6242ff (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100decision-question
    Ask the user to choose only when blocked on a decision they own, with the smallest complete decision brief. Use when you say `ask the user to choose`, `do I need a user decision here`, or `present a decision brief`. Do NOT use to review a decision already made (use…
  • 100ask-user-question
    Make the agent ask the user to choose between options through its structured question tool (Claude Code's AskUserQuestion or an equivalent) instead of a text list, and define the numbered text format for when the tool cannot be used. Use whenever the agent is about to ask the…
  • 95ask-decision
    Put the pending human decisions to the driver ONE AT A TIME, each with its context, its options with a recommended default first, the exact shape of the reply, and the act itself as a runnable block with how the desk verifies it afterwards. Use when the driver says "ask me…
  • 95ask-decision
    Put the pending human decisions to the driver ONE AT A TIME, each with its context, its options with a recommended default first, the exact shape of the reply, and the act itself as a runnable block with how the desk verifies it afterwards. Use when the driver says "ask me…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.