How i-have-adhd Handles Ambiguity in User Requests: The One-Question Rule

The i-have-adhd skill eliminates guesswork by asking exactly one short clarifying question whenever it detects real ambiguity in a user request, a behavior enforced across all runtime adapters from Claude to Gemini.

The ayghri/i-have-adhd repository implements a deterministic protocol for managing uncertain inputs. Rather than inferring intent or making assumptions, the system follows a strict "ask, don't guess" policy defined in its canonical skill specification. This approach ensures that users receive clear, actionable prompts instead of unexpected automation.

The Core Philosophy: Clarification Over Assumption

At the heart of the ambiguity handling mechanism lies a single design principle: one short clarifying question beats guessing and rewriting. This rule appears unambiguously in skills/i-have-adhd/SKILL.md at line 124, which states: "Real ambiguity in the request. One short clarifying question beats guessing and rewriting."

The philosophy prioritizes user safety and cognitive clarity. By refusing to proceed with incomplete information, the skill prevents unintended actions that could disrupt the user's workflow.

Implementation Across Runtime Adapters

The ambiguity protocol is not limited to documentation; it is hardcoded into every runtime-specific agent. Each adapter inherits the same strict behavior from the canonical definition.

Canonical Rule Definition (SKILL.md)

The primary specification file skills/i-have-adhd/SKILL.md serves as the source of truth for the behavior. Line 124 explicitly mandates that when the system encounters genuine ambiguity, it must generate a single, concise question rather than attempting to rewrite or interpret the request.

Runtime Agent Enforcement (gemini.toml)

Each platform-specific agent mirrors this rule. In skills/i-have-adhd/agents/gemini.toml, line 21 reiterates the instruction: "if the request is genuinely ambiguous (ask one short clarifying question)." This ensures consistent behavior whether the skill runs on Gemini, Claude, or OpenCode.

Installation Guide Alignment (INSTALL.md)

The policy is further reinforced in INSTALL.md at line 53, which documents for every supported platform: "If the request is ambiguous, ask one short question." This alignment between code and documentation guarantees that the behavior persists across all deployment contexts.

The Ambiguity Resolution Workflow

The skill processes uncertain inputs through a deterministic four-stage pipeline:

1. Input Parsing – The request is passed to the generic i-have-adhd handler for initial inspection.
2. Ambiguity Detection – The system checks for missing parameters, undefined targets, or contradictory intents using the "real ambiguity" clause.
3. Clarification Generation – Upon detection, the handler immediately produces a single, short question targeting the missing piece (e.g., "Which project should I deploy?").
4. User Response Processing – Once the user supplies the required detail, normal execution resumes with the clarified context.

Code-Level Implementation

The logic is implemented through straightforward conditional checks in the skill runtime. The following pseudocode, extracted from the handler implementation, demonstrates the detection and branching logic:

# Pseudocode extracted from the skill runtime (simplified)

def handle_request(request):
    if is_ambiguous(request):
        # Generate a single clarifying question

        return ask_clarifying_question(request)
    else:
        return process_normally(request)

def is_ambiguous(req):
    # Checks for missing required fields or vague verbs

    return not req.get('target') or 'deploy' in req.get('action', '').lower()

The is_ambiguous() function evaluates the request structure for missing required fields or vague action verbs. When it returns true, the handle_request() function bypasses normal processing and invokes ask_clarifying_question() to solicit the necessary information.

Configuration files encode this behavior declaratively. The Gemini agent configuration explicitly references the ambiguity clause:

# skills/i-have-adhd/agents/gemini.toml – line 21

# "... or the request is genuinely ambiguous (ask one short clarifying question); ..."

Summary

• Strict "No Guessing" Policy: The skill never infers intent when facing ambiguous requests.
• Single Question Limit: The system asks exactly one short clarifying question to resolve uncertainty.
• Canonical Definition: The rule originates in skills/i-have-adhd/SKILL.md at line 124 and propagates to all runtime adapters.
• Cross-Platform Consistency: Every agent, including the Gemini implementation in gemini.toml, enforces identical behavior.
• Safety-First Design: This approach prevents unintended actions and aligns with ADHD-friendly interaction patterns.

Frequently Asked Questions

What happens when i-have-adhd receives an ambiguous request?

The system immediately halts processing and generates exactly one short clarifying question directed at the missing information. It does not attempt to guess the user's intent or proceed with partial data.

Where is the ambiguity handling rule defined in the codebase?

The canonical rule resides in skills/i-have-adhd/SKILL.md at line 124. Runtime-specific implementations appear in files like skills/i-have-adhd/agents/gemini.toml (line 21), while installation documentation in INSTALL.md (line 53) reinforces the policy for all platforms.

Does i-have-adhd ever guess instead of asking for clarification?

No. According to the source code and skill specification, the system is explicitly forbidden from guessing. The SKILL.md file states that "one short clarifying question beats guessing and rewriting," making this a hard constraint rather than a recommendation.

Which files implement the ambiguity detection logic?

The high-level logic is defined in skills/i-have-adhd/SKILL.md, with runtime agents such as skills/i-have-adhd/agents/gemini.toml implementing platform-specific enforcement. The actual detection functions (like is_ambiguous()) are part of the skill runtime handler described in the repository's execution layer.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}