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.

| 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.