Menu
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
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use when analyzing a large corpus of text, code, or data that exceeds a single agent's effective context - orchestrates parallel Worker subagents, Critic review subagents, and a final Summarizer subagent with task tracking and failure recovery
Use to decide what kind of basic agent you should use
Use when creating a new opencode plugin or setting up plugin structure - provides complete file organization, manifest format, and component definitions for commands, agents, skills, hooks, and MCP servers
Use when creating specialized subagents for opencode or the task tool - covers description writing for auto-delegation, tool selection, prompt structure, and testing agents
Use when creating, releasing, or maintaining an opencode Plugin Marketplace - covers marketplace.json schema, version management, release checklists, changelog conventions, and validation to prevent sync drift between plugin.json and marketplace.json
Use when completing development phases or branches to identify and update AGENTS.md files that may have become stale - analyzes what changed, determines affected contracts and documentation, and coordinates updates
| 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 |
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."
Use this skill:
Do NOT use for:
Try to answer your own questions and disambiguate from the context of the working directory. Use available subagents, such as ed3d-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 ed3d-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 ed3d-haiku-general-purpose subagents to investigate them when they're appropriate.
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):
Impossible combinations:
Unacknowledged trade-offs:
How to surface:
Don't accuse - illuminate the tension:
Why first:
After contradictions are resolved, proceed to technical clarification.
When user mentions technical terms, disambiguate what they actually mean.
Examples:
User says "OAuth2" -> Ask: Which flow?
User says "database" -> Ask: Which kind?
User says "caching" -> Ask: What layer?
Use the question tool for these - present specific options with trade-offs.
When user mentions broad concepts, identify what's included and excluded.
Examples:
User says "users" -> Ask: Who exactly?
User says "integrate with X" -> Ask: What parts?
User says "reporting" -> Ask: What scope?
Use the question tool - present distinct scope options.
When user states requirements, verify the underlying reasons and constraints.
Examples:
User says "must use library X" -> Ask: Why?
User says "needs to be fast" -> Ask: How fast?
User says "should follow pattern Y" -> Ask: Which aspect?
Use open-ended questions for understanding "why" - allows user to explain context.
When user mentions external services or libraries, verify current state.
Examples:
User says "integrate with Stripe" -> Check:
User says "use React Router" -> Check:
Quick agent queries for factual checks:
Don't do deep research - save that for brainstorming. Just verify basics.
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:
Infer the Definition of Done from context gathered so far:
If you have a firm grasp, state it back and confirm:
Use the question tool:
"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)
If the deliverables are still ambiguous, ask targeted questions:
Why this matters: Brainstorming explores how to achieve the goal. The goal must be locked in first. Otherwise you're exploring texture without knowing what shape you're filling.
The Definition of Done becomes part of the output bundle and will appear prominently at the top of the final design document.
When there are 2-4 distinct options with trade-offs:
Question: "Which OAuth2 flow are you targeting?"
Options:
- "Authorization code flow" (human users with browser redirect)
- "Client credentials flow" (service-to-service automated auth)
- "Both flows" (supports human users AND service accounts)
Benefits:
When you need to understand reasoning or context:
"Why is X a requirement?" "What problem does Y solve?" "What happens if we don't include Z?"
Benefits:
When you need to verify something factual:
Don't get distracted - these are quick checks, not research projects.
After clarification, create a clear summary to pass to brainstorming:
Resolved trade-offs:
Clarified requirements:
Verified assumptions:
Scope boundaries:
This bundle gives brainstorming a concrete, unambiguous starting point.
| Mistake | Fix |
|---|---|
| Ignoring contradictions in requirements | Surface conflicting goals before technical clarification |
| Accepting vague terms at face value | Disambiguate every technical term |
| Assuming scope without verification | Ask explicit boundary questions |
| Not questioning "must have" requirements | Understand WHY behind constraints |
| Doing deep research during clarification | Quick checks only, save research for brainstorming |
| Proposing solutions while clarifying | Stay in understanding mode, no design yet |
| Skipping clarification when "seems clear" | Always clarify, assumptions are dangerous |
Stop and move to brainstorming when:
You don't need perfect information - just enough to brainstorm effectively.
If brainstorming reveals new ambiguities, you can return to clarification.
This skill sits between context gathering and brainstorming:
Context Gathering (starting-a-design-plan Phase 1)
-> User provides: "Build OAuth2 integration for our API"
Clarification (this skill)
-> Disambiguate: Which OAuth2 flow? What scope? Why OAuth2?
-> Output: Service accounts, client credentials, PCI compliance
Brainstorming (starting-a-design-plan Phase 3)
-> Explore: Architecture options, library choices, implementation phases
-> Uses clarified requirements as foundation
Purpose: Ensure brainstorming builds the right thing, not the wrong thing well.