JetBrains/thinkrail / packages/pi-thinkrail-workflow/skills/asking-user-questions
asking-user-questions
VerifiedUse 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.
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 inoptions[].preview— and, when the tool offerspreviewFile, a mockup file rather than pasted HTML or ASCII art.
Options
- Recommended option first, label suffixed "(Recommended)", plus a one-line
recommendedReasonsaying why you recommend it over the alternatives (shown inline under the option as aWhy: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
multiSelecttoo: 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: truewhen 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.headeris 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_questionis 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_questionreturns "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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 463k | Updated | Claude CodeCodex | Verified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 463k | Updated | Claude CodeCodex | Verified | Install |
| discernment-nudgeanthropics/skillsAfter you give a substantive answer or draft that the user may act on — advice or recommendations, drafted artifacts such as goals, plans, pitches, proposals, or emails, estimates or projections, analysis or interpretation of data, factual claims they may rely on, or a multi-step argument — invoke this skill BEFORE finalizing your reply and then, if it applies, append 2-3 short follow-up questions, each tied to something specific in what you just produced, that help the user check key facts, probe the reasoning or assumptions, and notice missing context. Do this at most once per conversation. Skip it when the user asked a trivial how-to or simple lookup, wants a purely educational explanation, asked you only to format, convert, or assemble a file from content they provided, is writing code they will run, is doing creative writing or casual chat, or already asked you to double-check, cite, or review — the skill file explains these boundaries and the exact output format. | Stars: 195k | Updated | Claude CodeCodex | Verified | Install |
| internal-commsanthropics/skillsA set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal communications (status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.). | Stars: 195k | Updated | Claude CodeCodex | Verified | Install |