Asking Clarifying Questions

Overview

Bridge the gap between raw user input and structured brainstorming by understanding what the user actually means, not what they said.

Core principle: Resolve contradictions first, then disambiguate. Conflicting goals must be reconciled before technical clarification - otherwise you're precisely defining the wrong thing.

Announce at start: "I'm using the asking-clarifying-questions skill to make sure I understand your requirements correctly."

When to Use

Use this skill:

• After gathering initial context from user
• Before starting brainstorming or design exploration
• When user mentions technical terms that could mean multiple things
• When scope boundaries are unclear
• When assumptions need verification

Do NOT use for:

• Exploring design alternatives (that's brainstorming)
• Proposing architectures (that's brainstorming)
• Validating completed designs (that's brainstorming Phase 3)
• Asking for initial requirements (that's starting-a-design-plan Phase 1)

Before Clarifying

Try to answer your own questions and disambiguate from the context of the working directory. Use available subagents, such as codebase-investigator, to explore for existing work that can help explain the the subject under clarification. When you recognize elements such as common technologies or proper nouns, use combined-researcher instead to synthesize both the codebase and internet searches.

You may have other skills or MCPs containing useful information, such as connections to remote datastores used for product management purposes. You should send out haiku-general-purpose subagents to investigate them when they're appropriate.

No nested subagents: Only the current caller may dispatch these research subagents. Tell each subagent to do the work directly and not to dispatch additional subagents.

What to Clarify

0. Contradictions (First Pass)

Before disambiguating technical details, scan for logical contradictions in requirements. If the user has stated mutually exclusive goals, resolve these first - technical clarification is wasted effort if the foundation shifts.

Look for:

Explicit contradictions (user stated both):

• "Real-time updates" + "batch processing is fine" → Which is the actual need?
• "Keep it simple" + "handle every edge case" → Trade-off not acknowledged
• "Use existing patterns" + "complete rewrite" → Mutually exclusive approaches
• "No external dependencies" + "integrate with Stripe" → Implicit contradiction

Impossible combinations:

• "Offline-first" + "always-current data" → Physics problem
• "Fast to build" + "infinitely extensible" → Classic impossible triangle
• "Zero latency" + "synchronous validation" → Can't have both
• "No breaking changes" + "fundamental redesign" → Pick one

Unacknowledged trade-offs:

• "Simple" often conflicts with "flexible"
• "Fast" often conflicts with "thorough"
• "Cheap" often conflicts with "custom"
• "Secure" often conflicts with "convenient"

How to surface:

Don't accuse - illuminate the tension:

• "I notice you mentioned X and Y - these can pull in different directions. Which takes priority?"
• "There's a trade-off between A and B here. Which matters more for this project?"
• "These two goals sometimes conflict - how should I balance them when they do?"

Why first:

• Contradictions reveal unconfronted trade-offs
• Resolving them changes what "right" means
• Technical disambiguation without this = building the wrong thing precisely

After contradictions are resolved, proceed to technical clarification.

1. Technical Terminology

When user mentions technical terms, disambiguate what they actually mean.

Examples:

User says "OAuth2" -> Ask: Which flow?

• Authorization code flow (for human users with browser redirect)
• Client credentials flow (for service-to-service auth)
• Both, depending on the use case

User says "database" -> Ask: Which kind?

• SQL (PostgreSQL, MySQL) for structured data
• NoSQL (MongoDB, DynamoDB) for flexible schema
• Already determined by existing infrastructure

User says "caching" -> Ask: What layer?

• Application-level (Redis, Memcached)
• HTTP caching (CDN, browser cache)
• Database query caching

Use AskUserQuestion for these - present specific options with trade-offs.

2. Scope Boundaries

When user mentions broad concepts, identify what's included and excluded.

Examples:

User says "users" -> Ask: Who exactly?

• Human users logging in via web browser
• Service accounts for API access
• Both, with different authentication flows
• Internal employees vs external customers

User says "integrate with X" -> Ask: What parts?

• Just authentication
• Full data sync
• Specific API endpoints
• Real-time webhooks vs batch imports

User says "reporting" -> Ask: What scope?

• Basic data export (CSV, Excel)
• Interactive dashboards
• Scheduled automated reports
• Real-time analytics

Use AskUserQuestion - present distinct scope options.

3. Assumptions and Constraints

When user states requirements, verify the underlying reasons and constraints.

Examples:

User says "must use library X" -> Ask: Why?

• Regulatory requirement (cannot change)
• Existing team expertise (preference, not hard requirement)
• Already in use elsewhere (consistency benefit)
• Misconception (might have better options)

User says "needs to be fast" -> Ask: How fast?

• Sub-100ms response time (hard requirement)
• Faster than current implementation (relative improvement)
• Perception of speed (optimistic UI, loading states)
• Actual performance bottleneck identified

User says "should follow pattern Y" -> Ask: Which aspect?

• Exact implementation (strict consistency)
• General approach (flexible adaptation)
• Just using same libraries (tooling consistency)
• Not actually required (outdated guideline)

Use open-ended questions for understanding "why" - allows user to explain context.

4. Version and API Specifics

When user mentions external services or libraries, verify current state.

Examples:

User says "integrate with Stripe" -> Check:

• Which Stripe API version (latest? specific?)
• Payment Intents API or older Charges API
• Which features needed (one-time, subscriptions, both)
• Already have Stripe account setup

User says "use React Router" -> Check:

• React Router v5 or v6 (breaking changes between versions)
• Already in use in codebase (follow existing patterns)
• Browser Router vs Hash Router vs Memory Router

Quick agent queries for factual checks:

• "What version of X exists?" -> Quick web search or codebase check
• "What's the current API?" -> Internet research for docs
• "Is Y already in use?" -> Codebase investigation

Don't do deep research - save that for brainstorming. Just verify basics.

5. Definition of Done (Required Final Step)

Before handing off to brainstorming, you MUST establish the Definition of Done.

The Definition of Done answers: "What does success look like? What are the deliverables?"

After resolving contradictions and clarifying requirements:

1. Infer the Definition of Done from context gathered so far:

   • What will exist when this is complete?
   • What will users/systems be able to do?
   • What are the concrete deliverables?

2. If you have a firm grasp, state it back and confirm:

   Use AskUserQuestion:
   "Based on our discussion, here's what I understand success looks like:
   
   [State the definition of done in 2-4 bullet points]
   
   Does this capture what you're trying to achieve?"
   
   Options:
   - "Yes, that's right" (proceed to brainstorming)
   - "Partially, but..." (user will clarify)
   - "No, let me explain..." (user will reframe)
   

3. If the deliverables are still ambiguous, ask targeted questions:

   • "What should exist when this is done?"
   • "How will you know this succeeded?"
   • "What's the minimum viable deliverable?"

Why this matters: Brainstorming explores how to achieve the go