clarify-idea

Clarify Idea

This skill encodes a short conversational clarification loop to run before structured idea extraction or task refinement, when the raw input is too ambiguous to extract cleanly. It is instructional — the calling agent drives the loop using its own AskUserQuestion tool. This skill does not spawn subagents.

When to invoke

Apply this checklist to the raw input. If any item is missing or unclear, invoke the loop:

• Goal — what outcome does the user want?
• Target user / surface — who/what is affected? Which screen, file, subsystem?
• Success signal — how will the user know it worked?
• Scope boundary — what is explicitly in or out of scope?
• Grounding — does the input reference concrete files, functions, features, or existing behavior?

If all five are present, skip this skill and proceed directly to extraction. Running the loop on an already-clear input is a cost, not a benefit.

Opt-out signals the caller must honor:

• --skip-clarify anywhere in the arguments
• config.phases.clarify === false in .soloflow/config.json or config/defaults.yaml

Anti-pattern

"This is too simple to need clarification."

The ambiguity checklist is the judge, not your intuition. Cheap to run, cheap to skip. Do not debate whether to invoke — apply the checklist.

Scope-decomposition gate (runs first)

If the input spans multiple independent subsystems or deliverables (e.g., "redesign onboarding AND add a notifications center AND refactor the API client"), stop immediately. Do NOT begin clarification on the whole thing.

Use AskUserQuestion:

• Question: "This request covers multiple independent pieces. Which one do you want to work on first?"
• Header: "Pick one"
• Options: one per detected subsystem, plus a free-form "something else" fallback.

Clarify only the selected piece. The others can be captured as separate ideas later.

Clarification loop

Rules (hard):

1. One AskUserQuestion at a time. Never batch clarification questions. Each answer informs the next question.
2. Prefer multiple-choice. Offer 2–4 concrete, mutually distinct candidate answers, plus the built-in free-form fallback the tool provides. Avoid open-ended prompts unless the space is genuinely unbounded.
3. Follow threads. An answer may reveal a new ambiguity — follow it. Examples:
   • Vague term → "When you say X, do you mean A, B, or C?"
   • Interpretation fork → "Two reasonable reads of this: which did you mean?"
   • Missing example → "Would {concrete scenario} count as success?"
4. Lightweight research is allowed, not required. One targeted Grep / Glob (or a single WebSearch for unfamiliar domain terms) is fine to frame better candidate answers. Never use research as a substitute for asking the user.
5. Do not propose slices, tasks, or implementations. This skill only disambiguates the ask. Structuring is the idea-extractor's job; planning is the task-refiner's job.