/clarification

name: clarification
description: Use when a user's request is vague, ambiguous, or underspecified. Explores the codebase first, then runs an iterative Q&A loop grounded in the findings until ambiguity is gone. Outputs a clear, well-scoped context brief so the user can plan sharply. Triggers on "I want to...", "I need...", "let's build...", "can you help me...", "we should...", or any request where the full scope isn't immediately clear.

Clarification Through Iterative Discovery

Narrows vague user requests into well-defined work scopes. Explores the codebase first, then asks questions grounded in what exploration found, iterating until ambiguity is gone.

Core Principle

Ambiguity does not resolve in one pass. Multiple rounds of exploration and questions intersect, gradually sharpening the picture. Exploration comes first: an agent that has seen the codebase asks confident, specific questions; an agent that hasn't asks generic ones and wastes the user's answers. The purpose of this skill is not "writing code" — it is making "what the user wants" and "what state the codebase is in" vivid and clear.

Hard Gates

1. **Explore before you ask.** Dispatch recon subagents BEFORE the first question. Every question must be grounded in exploration findings — never ask the user something the codebase can answer. 2. **Always use subagents.** Dispatch subagents before the first question, and again in response to the user's answers. 3. **Do not start implementation until you can say "this is clear enough."** Understanding must be complete at the codebase level. 4. **Every question must narrow scope.** Do not repeat questions at the same level of ambiguity. Independent questions may be bundled into one round (up to 4, e.g., via AskUserQuestion); dependent questions are asked iteratively. The loop ends when ambiguity is gone — not after a fixed number of rounds. 5. **Never dump raw code exploration results on the user.** Summarize findings in the context of the user's question.

When To Use

• The user says "I want to…" but the scope is unclear
• The request is vague enough that implementation could go in multiple directions
• The user themselves hasn't fully articulated what they want
• There's a risk of clashing with existing codebase structure, so exploration is needed

When NOT To Use

• The request is already specific and clear (proceed to implementation or plan skill)
• The scope is obvious, like a simple bug fix or config change
• The user explicitly says "don't ask questions, just do it"

The Process: Recon First, Then the Q&A Loop

Phase 0: Initial Recon (before any question)

On receiving the vague request, dispatch Explore subagent(s) immediately — before asking the user anything. The recon maps the territory the request likely touches: file structure, existing patterns, interface boundaries, recent related changes, test coverage.

While recon runs, analyze the request and list its ambiguities. Compose the first question round only AFTER recon returns, so every question can cite what the code actually looks like: "The codebase already handles X in `services/y.ts` — should this follow that pattern or replace it?"

Track 1: User Q&A (Ambiguity Resolution)

Ask the user questions to resolve ambiguity.

**Question principles:**

• Ground every question in exploration findings — cite what was found
• Bundle independent questions into one round (up to 4); ask dependent questions iteratively
• Offer choices when possible (A/B/C)
• When a new ambiguity emerges from an answer, drill into it in the next round
• Ask "which case?" rather than "why?" — draw out concrete scenarios, not abstract intent
• If an answer contradicts a previous one, flag it immediately and realign

**Question sequence guide:**

1. **Purpose**: "What is the end goal of this work?" (what they want to achieve) 2. **Scope**: "What's included and what's excluded?" (draw boundaries) 3. **Constraints**: "Are there existing constraints that affect this?" (time, compatibility, dependencies) 4. **Success criteria**: "What should the state look like when this is done?" (verifiable outcome) 5. **Priority**: "If there are multiple paths, what matters most?" (trade-offs)

After each question, briefly update "what we've established so far."

Track 2: Codebase Exploration (Technical Context)

Exploration starts before the first question (Phase 0) and continues between rounds — each user answer typically opens a new area worth exploring.

**How to dispatch exploration:**

Launch follow-up subagents as soon as an answer (or a prior finding) opens a new area — typically right after posing the next question round, so exploration runs while the user is answering. The subagent investigates:

• Related file structure and naming conventions
• Existing implementation patterns (error handling, state management, data flow)
• Dependencies and interface boundaries
• Recent change history (relevant commits)
• Test coverage status

**Subagent prompt template:**

subagent_type: Explore
description: "Explore [topic] codebase"
prompt: |
  The user has requested [summarized request].

  Investigate and report on:
  1. Related files and the role of each
  2. Existing implementation patterns (is something similar already in place?)
  3. Boundary areas this work is likely to affect
  4. Recent related changes
  5. Existing test state

  Report only key findings concisely.
  Do not dump entire file contents.

**Processing subagent results:**

When the subagent returns findings: 1. Cross-validate against the user's answers 2. If technical constraints unknown to the user are discovered, reflect them in the next question 3. If a conflict with existing code is likely, notify the user

Putting It Together: The Loop

digraph clarification {
    rankdir=TB;
    "User states vague request" [shape=box];
    "Dispatch recon subagents" [shape=box, style=dashed];
    "Assess ambiguities + receive recon findings" [shape=box]