---
name: clarifying-intent
description: Turn a vague or broad request into a written, approved brief before any planning or execution happens. Use when the ask is ambiguous, wide-ranging, or expensive to get wrong — 帮我看看 / 调研一下 / 做个方案 / 搞一下 / 优化下 / 分析一下. Asks one question per turn with concrete options, a recommendation, and the consequence of each choice, inside a strict budget so the user is never interrogated. Uses what is already installed on the machine to make questions concrete instead of abstract. Produces .superclarity/<task>/brief.md covering scope, non-goals, constraints, success criteria and assumptions. Do NOT use when the user already gave a complete brief, for one-step reversible tasks, or for plain factual questions.
license: MIT
metadata:
  pack: superclarity
  phase: clarify
---

# Ask the questions that change the plan

A user arrives with one sentence: "have a look at the competition", "tidy up our onboarding", "put together something on Q3". Starting work immediately burns an hour and a pile of tokens to deliver something aimed at the wrong target. The cost of asking is one turn. The cost of not asking is the whole task.

Answer the user in whatever language they wrote in.

## The anti-pattern: "this one is clear enough"

"UK sofa market" reads as perfectly clear. It does not say whether the interest is direct-to-consumer upstarts or established retailers, whether the reader is a design team or an investor, or whether anything behind a login counts. Those three unknowns produce three incompatible deliverables.

The feeling of clarity is not evidence of clarity. It usually means you have silently filled the blanks with your own defaults.

## But do not interrogate

Over-asking is why users switch clarification skills off, and a skill that is switched off clarifies nothing. Hold to the budget:

| Limit | Value |
| --- | --- |
| Questions total | at most 5 |
| Rounds | at most 3 |
| Questions per turn | 1 |

**The stop rule: if the answer would not change the plan, do not ask it.** Run every candidate question through it. Most fail.

Calibrate to the stakes. For low-risk reversible work, do not ask at all — **assume and flag**: state your two or three assumptions in one line, proceed, and let the user correct you cheaply. Save the budget for work that is expensive or irreversible.

## Ask questions only this machine could ask

Before the first question, read your own context: your tools, your installed skills and their descriptions, your subagents. It is free, and it turns a hollow question into a concrete one.

> Weak: "Which channels should this cover?"
>
> Strong: "I have a research skill installed that covers public web and social platforms, but nothing that can reach material behind a login. Should we (A) stick to public sources — fastest, and I would flag the gated report as uncovered; (B) you paste in the gated report; or (C) skip that source entirely? I recommend A unless that report is load-bearing for the decision."

The second question is answerable in five seconds because it carries the options, the recommendation, and the consequence. The first makes the user do your thinking.

## What every question needs

1. **Options**, usually two or three, concrete.
2. **A recommendation**, with the reason.
3. **The consequence** of each choice — what gets lost.

Never present a bare menu. "Which do you prefer?" transfers the decision without transferring the information needed to decide.

## What must be settled before planning

| Dimension | What goes wrong without it |
| --- | --- |
| **Outcome and audience** | Who reads this and what decision it feeds. Sets depth, format, and tone. |
| **Scope boundary** | What is in and, said out loud, what is out. Unstated exclusions become rework. |
| **Constraints** | Deadline, budget, required format, permitted sources, access limits. |
| **Done criteria** | How both of you will recognise good enough. Without it, nothing can be verified later. |

A loaded domain profile adds its own dimensions on top. Profile questions come after these four, never instead of them.

## When you can skip asking

Only one case: the user already supplied a complete brief — scope, boundaries, constraints, and success criteria all present. Even then, **restate it once in a short structured summary and get a yes.** A restatement takes ten seconds and catches the misreading that would otherwise surface at delivery.

## Close the loop

Write [`brief.md`](templates/brief.md) into `.superclarity/<task-slug>/`, show the user the summary, and get explicit approval before anything else happens. Approval of a brief you never showed is not approval.

Record every assumption you took, including the ones you took instead of asking. An assumption in writing is cheap to correct; the same assumption in your head is not.

## Worked example

The request: "help me pick a payroll vendor."

Introspection shows a research skill installed and no authenticated-browsing capability. Three questions, one per turn: who signs off and by when; whether the shortlist is fixed or you should build it; whether pricing must come from published tiers only or the user will supply quotes they have received.

Not asked, because the answers would not change the plan: which document format they prefer (ask at delivery), how many vendors is ideal (falls out of the shortlist answer), whether to include a vendor that does not operate in their country (disqualified by a stated constraint).

Three questions, one round of back-and-forth, and a brief that makes the plan almost write itself.