resolve-ambiguity
Systematic ambiguity resolution through tiered information gathering. Use when facing unclear requirements, unknown context, uncertain implementation choices, or any situation where guessing would be risky.
When & Why to Use This Skill
This Claude skill provides a systematic framework for resolving uncertainty through tiered information gathering. It empowers agents to autonomously navigate complex codebases, retrieve authoritative documentation, and engage in high-quality user clarification, effectively eliminating hallucinations and wasted effort caused by technical or intent-based ambiguity.
Use Cases
- Technical Requirement Clarification: Automatically searching project-specific configuration files and READMEs to determine the correct tech stack or dependency versions before writing code.
- Architectural Decision Support: Identifying existing design patterns within a repository to ensure new implementations remain consistent with the established project structure.
- External Documentation Retrieval: Using a multi-step search strategy to find official API references or library documentation when local context is insufficient.
- Intelligent User Interaction: Presenting structured, prioritized options to the user when intent is unclear, explaining the trade-offs of each choice to facilitate informed decision-making.
| name | resolve-ambiguity |
|---|---|
| description | Systematic ambiguity resolution through tiered information gathering. Use when facing unclear requirements, unknown context, uncertain implementation choices, or any situation where guessing would be risky. |
Core principle: Rather ask than guess. Wrong assumptions waste more time than clarifying questions.
When you encounter ambiguity, classify it:Technical/Factual - "How does X work?" "What is the correct syntax?" → Likely found in project or online sources → Follow the tiered lookup process
Intent/Choice - "Which approach should I use?" "What does the user want?" → Requires user input → Use AskUserQuestion immediately
If ambiguity is technical/factual:
→ Follow <tiered_lookup> process
Read
.claude/workspace-info.toon- Contains workspace structure, projects, capabilities, outcomes
- Shows current focus and IDE configuration
Read
.claude/project-info.toon- Contains project technology, dependencies, entry points
- Shows repository and IDE details
Task(subagent_type="Explore", model="haiku", prompt="""
Check for context files:
- .claude/workspace-info.toon
- .claude/project-info.toon
If found, extract relevant information about: {specific question}
Return only the relevant fields, not the entire file.
""")
**Check second - project-specific patterns**
Look within current scope for:
CLAUDE.md- Project instructions and conventionsREADME.md- Project overview and setupARCHITECTURE.mdordocs/architecture.md- Design decisions- Configuration files relevant to the question:
package.json,tsconfig.json(JavaScript/TypeScript)pyproject.toml,setup.py(Python)Cargo.toml(Rust).env.example(environment variables)
Glob for architectural files:
- **/CLAUDE.md
- **/README.md
- **/ARCHITECTURE.md
- **/docs/*.md
**Check third - if MCP documentation tools are available**
If MCP tools are available for documentation lookup:
- Use
mcp__context7__*for library documentation - Use
mcp__firecrawl__*for web documentation - Use other documentation-specific MCP tools
These provide structured access to official documentation.
**Check fourth - for external APIs, libraries, standards**Use WebSearch and WebFetch for:
- Official documentation sites
- GitHub repositories of libraries
- API reference documentation
- RFC or specification documents
Prefer sources in this order:
- Official documentation (*.dev, *.io, readthedocs)
- GitHub repository README/docs
- Stack Overflow with high votes (for edge cases)
If all tiers exhausted without answer → proceed to <user_clarification>
AskUserQuestion with structure:
- Question: Clear, specific question explaining context
- Options ordered by preference:
1. Best practice / Most common / Recommended
2. Good alternative
3. Another valid option
4. Least recommended / Has drawbacks
- Each option includes description explaining implications
- User can always select "Other" for custom input
Question: "Which authentication approach should I implement?"
Options (ordered best → least recommended):
- JWT with refresh tokens - Industry standard, stateless, works well with APIs
- Session-based auth - Simple, works well for server-rendered apps
- OAuth2 only - Good for social login, but adds complexity
- Basic auth - Simple but less secure, only for internal tools
Each option explains trade-offs so user can make informed choice.
When you cannot confidently identify the options:DO NOT GUESS. Ask an open-ended question instead.
AskUserQuestion:
- Question: Explain what you need to know and why
- Options:
1. A general direction if you have any hint
2. (Keep options minimal or omit entirely)
- Allow free-form input as primary response method
Instead of guessing configuration options:
Question: "I need to configure the database connection. What database are you using and what are the connection details?"
Options:
- I'll provide the details - Let me type the configuration
This is better than guessing "PostgreSQL" or "MySQL" when you don't know.
1. **Single question at a time** - Don't overwhelm with multiple questions 2. **2-4 options maximum** - More becomes confusing 3. **Descriptions are required** - Every option needs context 4. **No yes/no when options exist** - Offer the actual choices instead 5. **Acknowledge uncertainty** - "I'm not sure which applies, so..." **Examples**: "How do I call this API?" "What's the correct syntax?"Resolution path:
- Check project context files
- Check architectural docs
- WebSearch official documentation
- If still unclear → ask user for clarification
Resolution path:
- Check CLAUDE.md for explicit conventions
- Check existing code for patterns (Glob + Read)
- Check README/contributing guide
- If no clear pattern → ask user preference
Resolution path:
- Skip lookup - this requires user input
- AskUserQuestion immediately
- Present inferred options if confident
- Allow open-ended response if uncertain
Resolution path:
- Check package.json/pyproject.toml for versions
- WebSearch for current documentation
- WebFetch official docs
- If version-specific behavior → confirm with user
Resolution path:
- Check .env.example or config files
- Check project-info.toon
- Check README for setup instructions
- If sensitive values → ask user (never guess credentials)
Resolution path:
- Check ARCHITECTURE.md or design docs
- Check workspace-info.toon for project structure
- This is usually a choice → AskUserQuestion
- Present trade-offs clearly in options
- Information found: Authoritative source confirms the answer
- User clarified: User provided explicit direction
- Documented: Decision is captured for future reference
Signs of good resolution:
- No guessing occurred
- User wasn't asked unnecessary questions
- The answer came from the most appropriate source
- Forward progress is now possible