resolve-ambiguity

rayk/resolve-ambiguity

Planning

About

SKILL.md

Resolve ambiguity through a systematic process that prioritizes accurate information over guessing. This skill determines the best source for missing information and retrieves it efficiently.

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 about user intent or preference: → Skip lookup, go directly to `` section

If ambiguity is technical/factual: → Follow <tiered_lookup> process

For technical/factual ambiguity, check sources in this order. Stop as soon as you find authoritative information. **Check first - fastest and most relevant**

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 conventions
README.md - Project overview and setup
ARCHITECTURE.md or docs/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

1. WebSearch with specific query: "{library/API name} documentation {specific topic} 2024 2025" 2. WebFetch the most authoritative result (official docs preferred) 3. Extract only the relevant information

Prefer sources in this order:

Official documentation (*.dev, *.io, readthedocs)
GitHub repository README/docs
Stack Overflow with high votes (for edge cases)

Stop the tiered lookup when: - You find authoritative information that resolves the ambiguity - You've checked all relevant tiers without finding information - The information found indicates this is actually a choice/intent question

If all tiers exhausted without answer → proceed to <user_clarification>

For intent/choice questions, or when tiered lookup fails, ask the user directly. **Never guess when user input is available.** 1. **Explain what you need** - Tell the user what information is missing 2. **Explain why you need it** - Describe how the answer affects the outcome 3. **Offer smart choices** - If you can infer likely options, present them 4. **Best practice first** - Order choices with recommended approach at top 5. **Bad ideas last** - If including risky options, put them at the bottom 6. **Always allow custom input** - User can always provide their own answer 7. **When uncertain, don't guess choices** - Better to ask open-ended than offer wrong options When you can confidently identify the options:

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

**Examples**: "What naming convention?" "Where should this file go?"

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

**Examples**: "Which feature first?" "Should I also refactor X?"

Resolution path:

Skip lookup - this requires user input
AskUserQuestion immediately
Present inferred options if confident
Allow open-ended response if uncertain

**Examples**: "Which version of X?" "What's the API for Y?"

Resolution path:

Check package.json/pyproject.toml for versions
WebSearch for current documentation
WebFetch official docs
If version-specific behavior → confirm with user

**Examples**: "What port?" "What environment variables?"

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)

**Examples**: "Monolith or microservices?" "Which pattern to use?"

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

**Detect ambiguity**: Identify what information is missing and classify it: - Technical/Factual → Tier lookup - Intent/Choice → User clarification **For technical ambiguity**: Execute tiered lookup in order: 1. Project context files (.claude/*.toon) 2. Architectural files (CLAUDE.md, README, docs) 3. MCP documentation tools (if available) 4. WebSearch/WebFetch official sources **For intent ambiguity or lookup failure**: Use AskUserQuestion: - Explain what's needed and why - Offer choices ordered by recommendation (if known) - Don't guess choices if uncertain - Always allow custom input **Apply the answer**: Use the information to proceed with the task. Document any decisions made for future reference. Ambiguity is resolved when:

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

**Wrong**: Making assumptions and proceeding without verification **Instead**: Take 30 seconds to check or ask **Wrong**: Asking 5 questions before doing anything **Instead**: Ask only what's blocking immediate progress **Wrong**: "How should I proceed?" **Instead**: "Should I use approach A (benefit) or B (benefit)?" **Wrong**: "Should I use the factory pattern or strategy pattern?" **Instead**: Explain the options in plain terms with trade-offs **Wrong**: Silently using a default without mentioning alternatives **Instead**: "I'll use X (the standard approach). Let me know if you'd prefer Y."

SKILL.md

Resolve ambiguity through a systematic process that prioritizes accurate information over guessing. This skill determines the best source for missing information and retrieves it efficiently.

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 about user intent or preference: → Skip lookup, go directly to `` section

If ambiguity is technical/factual: → Follow <tiered_lookup> process

For technical/factual ambiguity, check sources in this order. Stop as soon as you find authoritative information. **Check first - fastest and most relevant**

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 conventions
README.md - Project overview and setup
ARCHITECTURE.md or docs/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.

Resolution path:

Check project context files
Check architectural docs
WebSearch official documentation
If still unclear → ask user for clarification

**Examples**: "What naming convention?" "Where should this file go?"

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

**Examples**: "Which feature first?" "Should I also refactor X?"

Resolution path:

Skip lookup - this requires user input
AskUserQuestion immediately
Present inferred options if confident
Allow open-ended response if uncertain

**Examples**: "Which version of X?" "What's the API for Y?"

Resolution path:

Check package.json/pyproject.toml for versions
WebSearch for current documentation
WebFetch official docs
If version-specific behavior → confirm with user

**Examples**: "What port?" "What environment variables?"

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)

**Examples**: "Monolith or microservices?" "Which pattern to use?"

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