Claude Code Plugins

Community-maintained marketplace

Feedback

resolve-ambiguity

@rayk/lucid-toolkit
1
0

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.

Install Skill

1Download skill
2Enable skills in Claude

Open claude.ai/settings/capabilities and find the "Skills" section

3Upload to Claude

Click "Upload skill" and select the downloaded ZIP file

Note: Please verify skill by going through its instructions before using it.

SKILL.md

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.
allowed-tools Read, Glob, Grep, WebSearch, WebFetch, AskUserQuestion, Task
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:

  1. Technical/Factual - "How does X work?" "What is the correct syntax?" → Likely found in project or online sources → Follow the tiered lookup process

  2. 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**

  1. Read .claude/workspace-info.toon

    • Contains workspace structure, projects, capabilities, outcomes
    • Shows current focus and IDE configuration

  2. 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:

  1. Official documentation (*.dev, *.io, readthedocs)
  2. GitHub repository README/docs
  3. 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):

  1. JWT with refresh tokens - Industry standard, stateless, works well with APIs
  2. Session-based auth - Simple, works well for server-rendered apps
  3. OAuth2 only - Good for social login, but adds complexity
  4. 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:

  1. 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:

  1. Check project context files
  2. Check architectural docs
  3. WebSearch official documentation
  4. If still unclear → ask user for clarification
**Examples**: "What naming convention?" "Where should this file go?"

Resolution path:

  1. Check CLAUDE.md for explicit conventions
  2. Check existing code for patterns (Glob + Read)
  3. Check README/contributing guide
  4. If no clear pattern → ask user preference
**Examples**: "Which feature first?" "Should I also refactor X?"

Resolution path:

  1. Skip lookup - this requires user input
  2. AskUserQuestion immediately
  3. Present inferred options if confident
  4. Allow open-ended response if uncertain
**Examples**: "Which version of X?" "What's the API for Y?"

Resolution path:

  1. Check package.json/pyproject.toml for versions
  2. WebSearch for current documentation
  3. WebFetch official docs
  4. If version-specific behavior → confirm with user
**Examples**: "What port?" "What environment variables?"

Resolution path:

  1. Check .env.example or config files
  2. Check project-info.toon
  3. Check README for setup instructions
  4. If sensitive values → ask user (never guess credentials)
**Examples**: "Monolith or microservices?" "Which pattern to use?"

Resolution path:

  1. Check ARCHITECTURE.md or design docs
  2. Check workspace-info.toon for project structure
  3. This is usually a choice → AskUserQuestion
  4. 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."