---
name: asking-user-questions
description: "Use when composing an ask_user_question round inside a workflow, or when a workflow skill names it at a question step. Shared norms for the tool — not a workflow, nothing to execute."
title: asking-user-questions
canonical_url: https://skilld.dev/gh/jetbrains/thinkrail/asking-user-questions
last_updated: 2026-11-12T02:19:16.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install jetbrains/thinkrail/asking-user-questions`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/asking-user-questions`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jetbrains/thinkrail/asking-user-questions) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/asking-user-questions`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/asking-user-questions --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/asking-user-questions --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Asking User Questions

The workflow family's shared norms for `ask_user_question`: how to interview in rounds, what makes a
question worth asking, how to shape options, and how to degrade when answers don't come. Process
skills name this concept at the steps that ask; *when* to ask — and where the answers get recorded —
stays with the referencing skill.

## Interview in rounds until nothing is assumed

- Map the subject as a **design tree**: every decision branches into the decisions that hang off it.
  The **frontier** is every open decision whose prerequisites are already settled — the questions you
  can ask *now* without guessing at answers you haven't heard.
- One call = one **round** = the whole frontier, with no cap on its size. A question whose answer
  depends on another question still open belongs to a *later* round, never the same one. Never split
  independent questions across back-to-back calls.
- **The call blocks the current run.** Answers arrive as this tool's result. Don't keep working on the
  blocked step or assume an answer until it arrives — seconds or days later. A composer message sent
  while the card is open supersedes the round: the card closes unanswered and the message arrives as
  the next user message, so treat it as the user's reply and re-ask only what still matters.
- After each round, recompute the frontier: answers settle branches, unblock their dependents, and
  prune branches that no longer apply. Ask the next round; never pre-write later rounds.
- The interview is done when the frontier is empty — every branch visited, nothing material silently
  assumed. Then continue the referencing skill's next step; there is no extra "are we aligned?" round
  (the referencing skill's own gates still apply).
- Depth follows the work, not a quota: work with no open user decision gets zero rounds; a
  decision-heavy change may take several.

## Facts are yours, decisions are theirs

- Never ask the user for a fact the workspace, the specs, or the web can answer. Look it up. When a
  lookup is slow, start it in the background (a sub-agent, when the host offers one) and ask the rest
  of the frontier meanwhile — only the questions downstream of that lookup wait.
- Every decision — scope, observable behavior, trade-offs the user will live with — goes to the user.
  Picking an option yourself and moving on is answering your own question, not inferring.
- If candidate options differ only internally — identical observable behavior — it is not a user
  decision: decide yourself and record the reasoning in the workflow's artifact.

## What makes a question worth asking

- **It changes the outcome.** Each answer leads somewhere different that the user will see or live
  with. If every option ends in the same place, drop the question.
- **It is specific to this work.** Name the actual feature, screen, file, or user ("when a project is
  renamed while collapsed…"), never a generic template question.
- **It probes what people silently assume.** Sweep the tree's usual blind spots: scope edges and
  non-goals, empty / error / failure states, edge cases and limits, concurrency or multiple
  instances, existing data and behavior that must migrate or stay, defaults, and who the work is for.
- **It surfaces tension.** A conflict with a recorded spec decision, an earlier answer, or the
  request itself is asked about outright, quoting both sides.
- **It never re-asks.** Anything the request, a prior answer, or the specs already settled is
  settled; build on it.
- **A concrete scenario beats an abstract principle.** Ask "a user drags a file onto a busy session —
  queue it or reject it?", not "how should concurrency be handled?".
- If the question can't be settled by talking (how something should look or feel), show a concrete
  artifact instead of describing it: what the question is about (the design to approve, the current
  state) in `questions[].preview`, the alternatives in `options[].preview` — and, when the tool offers
  `previewFile`, a mockup file rather than pasted HTML or ASCII art.

## Options

- Recommended option first, label suffixed "(Recommended)", plus a one-line `recommendedReason` saying
  why you recommend it over the alternatives (shown inline under the option as a `Why:` line).
- Every option: a concise label (1–5 words, ≤ 60 chars) + a description carrying the trade-off or
  consequence of choosing it. Tailor options to the work at hand — never generic placeholders.
- Options must be **decidable by the asked user**: frame them as observable behavior or outcomes
  ("collapsing a project stays collapsed after a rename"), never as implementation mechanics
  ("semantic guard", "activation ref").
- Never author your own "Other", free-text, escape or "discuss"-style options ("None of these",
  "Not this — ask me differently") — the tool adds a free-text row and a way to mark the question
  "discuss first" to every question, plus an always-available Skip, and reserved labels are rejected.
  This holds under `multiSelect` too: the free-text row stays and is *additive* — a typed answer arrives
  alongside the checked options, it does not replace them.
- A question the user marks **discuss first** (with an optional reason: unclear, not relevant, needs
  more context) is not answered: never settle it on a guess. Explain it in plain words — what is being
  decided and why it matters, or whether it is needed at all when it seems not relevant — and ask it
  again in a later round.
- `multiSelect: true` when several answers are valid at once (feature checklists); single-select when
  confirming something or choosing one path.
- `options[].preview` (markdown) when a concrete artifact — code, a config, a mockup — is clearer
  shown than described. Single-select only; an option may honestly have none.
- `header` is a short chip, ≤ 16 characters.

## Confirming an inference

When you have inferred something and need a yes/adjust rather than an open answer: the inferred
statement *is* the question text, with a single "Looks right" option (description: "accurate as
written"). Edits arrive through the tool's automatic free-text row and disagreement through its
"discuss first" mark — do not author an edit or rejection option. Read the response as:

- **"Looks right"** → the inference holds; continue unchanged.
- **Free-text tweak** (one fact changes) → update that field only; don't re-derive anything else.
- **Substantial rewrite** → re-derive every inference that came from that statement before continuing.
- **Discuss first** → the inference is not confirmed: discard it, then explain what you inferred and why
  (for "unclear" or "needs more context") or ask an open-ended question instead.

## Degradation

- A skipped or declined question is not a blocker: settle it on your recommended answer, recorded as
  unconfirmed in the workflow's artifact (the referencing skill says where), and keep working its
  dependents from that assumption — don't re-ask it.
- A whole round skipped means the user wants to stop being interviewed: ask no further rounds and
  proceed on recorded assumptions for everything still open.
- If `ask_user_question` is not among your tools (switched off in the host, or never installed), ask
  the round as a plain chat message instead: the same frontier, each question with its numbered
  options and the recommended one first with its reason. Then end the turn and wait for the reply;
  never trade the missing tool for a guess. Read the reply as the round's result, and a question it
  leaves unanswered counts as declined.
- If the host reports no interactive UI (`ask_user_question` returns "not available"), state your
  assumptions the same way instead of blocking.
- "I don't know / help me understand" is a mis-framing signal, not a missing-knowledge one: re-explain
  from user-visible behavior in plain language, then re-ask with behavior-framed options — don't
  repeat the same technical options with more detail.

## Red flags

- You stopped after one round while decisions that depended on its answers are still open.
- You chose an option for the user instead of asking — or asked the user something you could have
  looked up.
- One round holds two questions where one answer would change the other.
- A question restates what the request or an earlier answer already settled.
- Every question would fit any project — nothing names this work's specifics.
