/asking-clarifying-questions

name: asking-clarifying-questions
description: Use after initial design context is gathered, before brainstorming - resolves contradictions in requirements, disambiguates terminology, clarifies scope boundaries, and verifies assumptions to prevent building the wrong solution
user-invocable: false

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 implementa