--- name: Intent Clarifier slug: intent-clarifier category: AI Engineering description: Intent Clarifier scores request ambiguity and routes it into the right phase. It generates structured, option-rich questions when a request needs clarification before delegation. github: "https://github.com/withkynam/vibecode-pro-max-kit/tree/main/.claude/skills/vc-intent-clarify" language: JavaScript stars: 1085 forks: 227 install: "npx degit https://github.com/withkynam/vibecode-pro-max-kit/tree/main/.claude/skills/vc-intent-clarify ~/.claude/skills/vc-intent-clarify" installs_to: ~/.claude/skills/vc-intent-clarify source_path: .claude/skills/vc-intent-clarify/SKILL.md collection_size: 25 category_size: 2451 collection_url: "https://dirskills.com/collections/withkynam/vibecode-pro-max-kit" added: 2026-08-20T07:56:52.381Z last_synced: 2026-08-20T07:56:52.381Z canonical_url: "https://dirskills.com/skills/intent-clarifier" --- # Intent Clarifier Intent Clarifier scores request ambiguity and routes it into the right phase. It generates structured, option-rich questions when a request needs clarification before delegation. **Install:** ```bash npx degit https://github.com/withkynam/vibecode-pro-max-kit/tree/main/.claude/skills/vc-intent-clarify ~/.claude/skills/vc-intent-clarify ``` ## README # vc-intent-clarify > Output style: lead each question with the recommended option; plain language, no filler — `process/development-protocols/communication-standards.md`. Two-mode intent clarification: SIMPLE (direct, 3-5 reads) and DEEP (research subagent first, then questions). Scores a user request's ambiguity and — when Tier 2 triggers — produces a structured, multi-dimension clarification suite with option-rich questions rather than open-ended prompts. Uses vc-scenario, vc-predict, and vc-sequential-thinking style reasoning to generate questions, not just to answer them. This is the highest-leverage skill in the system. Poor intent clarification wastes entire phase programs. Invest in the question generation step. --- ## When To Invoke At ORCHESTRATOR before every routing decision for new user requests. Check auto-skip conditions first. If none apply, score the four signals and act on the resulting tier. --- ## Auto-Skip Conditions These conditions force Tier 0 regardless of the ambiguity score. Check these FIRST. 1. Continuation phrases — "go", "continue", "proceed", "just do it", or similar standalone instruction 2. Mid-phase-program execution — active phase plan is selected and approved, user is advancing 3. Trivial fix — single-file, under 15 lines, no schema/API/auth changes 4. Explicit mode command — "ENTER EXECUTE MODE", "ENTER RESEARCH MODE", etc. 5. Resuming active plan — an existing active plan is identified and confirmed 6. Pure information question — "What is X?", "How does Y work?" mapping to a single obvious routing target When an auto-skip condition matches, produce only a 1-sentence restatement of intent and route immediately per the existing routing protocol. Do not announce the tier. Do not surface any questions. **Priority ordering when multiple conditions match simultaneously:** 1. Explicit mode command (highest priority) 2. /goal mid-program execution 3. Continuation phrase 4. Trivial fix / active-plan resume (lowest priority) 5. Pure information question / resuming active plan (lowest priority — treated as Tier 0, auto-route to vc-research-agent or answer directly) Apply only the highest-priority matching condition's abbreviated behavior. Do not combine behaviors from multiple matching conditions. **Under /goal autonomous execution:** Even when an auto-skip condition matches and Tier 0 applies, the 1-sentence restatement MUST be emitted to the chat log as an audit entry. Never skip the restatement emit under /goal — it proves Tier-0 ran and serves as the audit log for that phase's intent confirmation. --- ## 4-Signal Scoring Formula Each signal is worth +1. Sum to get the ambiguity score. | Signal | Description | |--------|-------------| | Ambiguous scope | Request touches multiple features or packages without naming one | | No explicit path | No file, package, or feature name mentioned | | Multiple intents | Request could be a bug fix, feature, refactor, or question | | First interaction | No established workflow context in current session | Score thresholds: | Score | Tier | Action | |-------|------|--------| | 0–1 | Tier 0 | Auto-route silently | | 2 | Tier 1 | Show routing summary, wait for confirmation | | 3+ | Tier 2 | Full structured clarification suite | --- ## Mode Selection Before running any tier, the orchestrator selects the operating mode. Mode affects only HOW option values are populated in questions — the question FORMAT, CRITICAL/USEFUL grouping, and wait-for-go-ahead footer are identical in both modes. ### SIMPLE MODE (default) - Orchestrator runs the skill directly in the main thread - 3–5 file reads max (the Light Research Pass below) - Works when concrete option values can be derived from active plans + context routing alone - No subagent spawning **Trigger conditions (all must be true for SIMPLE):** - Ambiguity score ≤ 3 - Request is scoped to a known file, package, or named feature - Orchestrator can fill option values from active plans + context routing alone - Continuation, resume, or single-package scenario ### DEEP MODE - Spawns a full research subagent BEFORE generating questions - The subagent returns structured findings; the orchestrator uses those findings to populate question options with real file paths, concrete values, and risk-aware implications - No generic `{X}` placeholders ever — this mode's entire purpose is to eliminate them - Questions are materially better because they are grounded in actual codebase discovery **Trigger conditions (any ONE triggers DEEP):** - Ambiguity score is 4/4 (all four signals) - Request involves a phase program kickoff (new umbrella + N phases) - Request touches 3+ packages or feature folders - Request involves an architectural decision (new pattern, library swap, schema design) - User explicitly requests deep analysis ("deep dive", "investigate before asking", "thorough") - Orchestrator judges that good option values CANNOT be generated without a codebase scan --- ## Deep Mode — Research Subagent Protocol When DEEP MODE is triggered, the orchestrator spawns a research subagent before generating questions. The subagent's only job is to return raw findings — it does NOT generate questions. ### Research Subagent Prompt Template Pass this prompt to the subagent verbatim, substituting the bracketed values: ``` INTENT CLARIFY — DEEP MODE RESEARCH Request: [user's exact request] Relevant feature: [if known, else "unknown"] Active plans found: [list from plan-discovery] Your job: investigate the request deeply so the orchestrator can generate high-quality clarifying questions. Required steps (all must run): 1. vc-review-situation — current branch, worktrees, active plans, uncommitted changes 2. vc-scout — scan codebase for files/modules relevant to: [keywords from request] 3. vc-sequential-thinking — map the decision dimensions: what must be decided first? what is downstream? 4. vc-scenario — for each plausible interpretation: what are the top 3 failure modes? 5. vc-predict — 5-persona debate: senior dev / PM / security reviewer / QA / end user — what does each want to know before starting? Return structured output with these sections: - DISCOVERED CONTEXT: actual file paths, module names, package names found - DECISION DIMENSIONS: ordered list of decisions that have downstream impact - RISK SURFACE: for each interpretation, top 2 failure modes - PERSONA DISAGREEMENTS: what different stakeholders would want prioritized differently - CONCRETE VALUES: real paths, command strings, feature names to use in question options Do NOT generate questions — that is the orchestrator's job. Just return raw findings. ``` ### After Receiving Subagent Output The orchestrator uses the subagent's `DISCOVERED CONTEXT` and `CONCRETE VALUES` sections to replace every option value in the Tier 2 question suite. The question generation steps (Steps 1–6 in Tier 2 below) proceed as normal, but option text is populated from real findings instead of the light research pass. --- ## Tier 0: Silent Auto-Route No user interaction added. Score 0–1 or auto-skip triggered. Route to the detected agent per the existing routing protocol. Do not show a routing summary. --- ## Tier 1: Routing Summary Perform a light research pass (see section below). Then present: ``` Routing: [detected intent] → [target agent] Scope: [what I think you want changed] Plan: [existing plan if found, or "new work"] ``` WAIT for the user's next message before routing. Do NOT route in the same response. Do NOT say "I'll proceed unless you correct me." If the user confirms, proceed. If the user corrects, re-score and re-route. --- ## Tier 2: Full Structured Clarification Suite Tier 2 is the core of this skill. When triggered, the orchestrator does the following: ### Step 1 — Research pass (mode-dependent) **In SIMPLE MODE:** Perform a light research pass (see Light Research Pass section). Budget: 3–5 file reads. Scan active plans, context routing table, recent git state, and the named file/package if any. This populates concrete values in question options. **In DEEP MODE:** The research subagent has already run (see Deep Mode section above) and returned structured findings. Use the `DISCOVERED CONTEXT` and `CONCRETE VALUES` sections from those findings instead of performing a light research pass. Skip the 3–5 file read budget — the subagent already covered it. In both modes, the goal of Step 1 is identical: replace every generic placeholder in question options with concrete values (package paths, plan IDs, file names, feature names). ### Step 2 — Question generation using vc-scenario + vc-predict style reasoning Before writing the questions, THINK across these axes: - What are the plausible failure modes if we pick the wrong scope? (vc-scenario thinking) - What would 5 different people (senior dev, PM, security reviewer, QA, end user) want to know before starting? (vc-predict thinking) - What ordering of decisions has the most downstream impact? (vc-sequential-thinking) Use this analysis to GENERATE questions — not to answer them. The goal is to surface the decisions that, if made wrong, will cause the most rework. ### Step 3 — Classify each dimension as CRITICAL or USEFUL - **CRITICAL** — getting this wrong derails the entire phase or causes rework - **USEFUL** — helpful context but can default to recommendation without blocking CRITICAL dimensions appear first. The user can say "skip useful questions" to answer only CRITICAL ones. ### Step 4 — Format each question using AskUserQuestion tool **REQUIRED: use the `AskUserQuestion` tool to render all Tier 2 questions.** Do NOT render questions as markdown text. The AskUserQuestion tool renders clickable option selections in the Claude Code UI, which is far faster for the user than typing answers. **How to call it:** - Pass all questions in a single `AskUserQuestion` call (up to 4 per call) - Group CRITICAL questions into the first call(s), USEFUL questions after - Use `multiSelect: false` for mutually exclusive choices (default) - Use `multiSelect: true` only when the user genuinely needs to pick multiple options (e.g. "which packages are in scope") - The `header` field (max 12 chars) is the chip label — use the dimension name abbreviated - Set `description` to the 1–2 sentence consequence explanation - Each option `label` is the short choice text; `description` is the implication **Option rules (same as before, now applied to AskUserQuestion fields):** - Minimum 3 options per question (the tool supports up to 4; always include an "Other" option as the last one) - Mark exactly one option as `(Recommended)` by appending it to the label: `"Sequential — single agent (Recommended)"` - Fill option labels with concrete values from the research pass (real file paths, package names, plan IDs) — never generic placeholders - The "Other" option label: `"Other"` with description: `"Describe your preference in the next message"` **If AskUserQuestion is unavailable** (tool not in scope, non-interactive context): fall back to the markdown format below, but always prefer the tool when available. ``` **Q[N]: [Question title]** [1–2 sentences explaining why this decision matters and what goes wrong if we choose incorrectly.] Options: A) [option] — [implication] *(Recommended)* B) [option] — [implication] C) [option] — [implication] D) Other: describe your preference ``` ### Step 5 — Group questions by dimension with headers Each dimension header format: ``` ### [Dimension name] 🔴 CRITICAL ``` or ``` ### [Dimension name] 🟡 USEFUL ``` ### Step 6 — Emit wait-for-go-ahead footer After all questions, always emit: > Answer what you want — partial answers are fine. I'll use the *(Recommended)* defaults for anything you skip. Ready to proceed when you confirm. Do NOT route to any subagent before receiving at least a partial response or explicit "go". --- ## The 8 Standard Dimensions For a substantial request, cover all 8 dimensions. For a narrower request, use only the dimensions that are genuinely ambiguous. Do not pad — every question should require a real decision. ### Dimension 1 — Scope and Boundaries 🔴 CRITICAL Clarify what changes and — equally important — what must NOT change. Example questions: - Which packages/files are in scope? - Are there components or APIs that must remain untouched? - Is this isolated to one package or cross-cutting? ### Dimension 2 — Success Criteria 🔴 CRITICAL Clarify what the user truly wants to see as a result. Example questions: - What does "done" look like to you? - Is the goal a passing test suite, a deployed change, a passing code review, or visible UI behavior? - Is there a specific user action or flow that must work? ### Dimension 3 — Failure Modes and Risk Surface 🔴 CRITICAL Clarify what the user is most worried about going wrong. Example questions: - What are the most likely ways this change breaks something? - Are there auth, billing, schema, or public API surfaces this touches? - Is there a rollback requirement? ### Dimension 4 — Prior Context 🟡 USEFUL Clarify what has already been tried or is already in progress. Example questions: - Is there an existing plan file for this? - Has this been attempted before? What happened? - Is this a continuation of recent work (visible in git status or active plans)? ### Dimension 5 — Priority and Urgency 🟡 USEFUL Clarify the expected speed/quality tradeoff. Example questions: - Is this a hotfix that needs to ship now, or a proper implementation with full plan/test coverage? - Does this block other work in flight? - Quick patch acceptable, or must it be production-grade immediately? ### Dimension 6 — Autonomy Boundaries 🟡 USEFUL > **Autopilot Mode — CRITICAL promotion:** When an autopilot trigger phrase is detected, > Dimension 6 is treated as 🔴 CRITICAL rather than 🟡 USEFUL. It must appear in the > first AskUserQuestion call alongside the CRITICAL dimensions, not after them. The question > must explicitly name the three hard stops and ask the user to confirm they understand those > remain manual-first gates. Clarify how much the agent can decide on its own vs. checkpoint with the user. Example questions: - Can the agent pick the implementation approach, or does the user want to choose? - Should the agent pause for approval before destructive changes (schema migrations, API removals)? - Is a /goal-style autonomous run acceptable, or does each phase need a checkpoint? Autopilot-specific example (when trigger detected): - "This run will proceed autonomously. The following gates remain manual regardless: (1) irreversible/outward-facing actions not in the validate-contract, (2) live-provider billed feasibility probes (cost-class: needs-live-provider), (3) cascade BLOCKED (two consecutive phases BLOCKED). All other gates auto-proceed. Are there any additional gates you want to keep manual for this run?" ### Dimension 7 — Technical Constraints 🟡 USEFUL Clarify any specific libraries, patterns, or constraints the solution must conform to. Example questions: - Is there a specific library or pattern required? - Are there style/lint rules that constrain the approach? - Must the solution work in a specific runtime environment (Bun vs Node, edge vs server)? ### Dimension 8 — Phase Program Questions 🔴 CRITICAL (multi-phase only) Only include when the request implies multiple dependent phases or a long-running program. Example questions: - Should phases run sequentially or can some parallelize? - Which phase is the hard dependency for the rest? - What is the acceptable stopping point if a later phase is blocked? --- ## Full Tier 2 Example Below is a complete example of good Tier 2 output for a request like "refactor the billing flow to add credit top-up support." --- **Intent understood:** Add credit top-up support to the billing flow. Before routing, I need to resolve a few key decisions. --- ### Scope and Boundaries 🔴 CRITICAL **Q1: Which layers does this change touch?** Getting scope wrong here means re-opening files mid-phase and invalidating earlier test gates. Options: A) Prisma schema + tRPC billing router + UI billing page — full stack *(Recommended)* B) tRPC billing router + UI only — skip schema migration for now C) UI only — wire to existing endpoints, validate assumptions first D) Other: describe your preference **Q2: Which existing billing surfaces must NOT change?** We need to know what is off-limits before touching shared code paths. Options: A) Stripe webhook handlers and subscription models are frozen *(Recommended)* B) Only the credit transaction model is frozen C) Nothing is frozen — all billing code is in scope D) Other: describe your preference --- ### Success Criteria 🔴 CRITICAL **Q3: What does "done" look like?** If the success bar is wrong, the agent will stop too early or overshoot. Options: A) User can trigger a top-up from the UI and credit balance updates — end-to-end *(Recommended)* B) Backend complete with tests passing; UI is out of scope for this phase C) Plan written and approved — no implementation yet D) Other: describe your preference --- ### Failure Modes and Risk Surface 🔴 CRITICAL **Q4: Is there a risk surface we must protect?** Billing changes can silently double-charge or under-credit users if guard logic is missing. Options: A) Add explicit idempotency key to the top-up Stripe call *(Recommended)* B) No idempotency needed — amount is small enough that duplicates are acceptable C) Not sure — flag for code review D) Other: describe your preference --- ### Priority and Urgency 🟡 USEFUL **Q5: Speed vs. quality tradeoff?** Affects whether we write a full plan with validate-contract or skip to a lightweight execute. Options: A) Proper plan + validate-contract + full test coverage *(Recommended)* B) Quick implementation with tests deferred to a follow-up C) Research and plan only — no implementation this session D) Other: describe your preference --- > Answer what you want — partial answers are fine. I'll use the *(Recommended)* defaults for anything you skip. Ready to proceed when you confirm. --- ## Bad vs. Good Question Format Understanding the failure modes in question generation: ### Bad (open-ended, no options) ``` Q: What scope should the refactor cover? ``` This forces the user to type a free-form answer. Slow. Vague. Hard to act on. ### Bad (only 2 options, no recommendation marked) ``` Q: Full stack or UI only? A) Full stack B) UI only ``` Binary questions miss the third path. No recommendation means the user has no default to accept. ### Bad (generic placeholders left in) ``` Q: Which areas? [A] just {X} [B] {X} and {Y} ``` Placeholders not replaced with concrete values from light research. Signals the skill was invoked lazily. ### Good ``` **Q1: Which packages does this refactor touch?** Scope determines which test gates apply and which blast-radius files need review before touching code. Options: A) packages/api/src/router/billing.ts + apps/web/src/app/billing — full stack *(Recommended)* B) apps/web/src/app/billing only — frontend changes, read-only backend exploration C) packages/api/src/router/billing.ts only — backend logic, no UI changes yet D) Other: describe your preferred scope ``` --- ## Autonomy Mode ### What Grants Autonomy - Explicit autonomy phrases: "you decide", "just do it", "full autonomy", "don't ask", "autonomous" - Mid-phase-program context where the current phase plan is selected and approved - User has answered Tier 2 questions and said "go" - Autopilot Mode trigger phrase detected (see `orchestration.md §Autopilot Trigger Routing`): autonomy is granted for the full run scope. Dimension 6 (Autonomy Boundaries) is treated as CRITICAL rather than USEFUL for this session. ### Phrase Matching Rule Autonomy phrases must be standalone statements or sentence-initial. They do NOT match when embedded in des