Vc Intent Clarify

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.

Score thresholds:

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.