How the i-have-adhd Skill Handles Errors in AI Responses: A Strict Matter-of-Fact Approach

The i-have-adhd skill handles AI response errors by enforcing a strict two-part format: stating the factual cause followed by the exact fix, eliminating emotional or ambiguous language.

The i-have-adhd skill is an open-source project designed to optimize AI interactions for users with ADHD. One of its core design principles is radical clarity in error reporting. Rather than allowing AI models to generate vague, apologetic, or emotionally loaded error messages, the skill imposes a rigid structure that helps users immediately understand what went wrong and what to do next.

The Two-Part Error Format

According to the skill's specification in SKILL.md (lines 98-104), every error in an AI response must contain:

• Cause — a concise, factual explanation of why the error occurred
• Fix — the precise corrective action required to resolve the problem

This structure removes cognitive overhead. Users don't need to interpret tone, parse ambiguity, or guess at next steps.

Where the Rule Is Enforced

The error-handling requirement appears in two critical configuration files:

SKILL.md — The Core Specification

In skills/i-have-adhd/SKILL.md, the "Matter-of-fact tone for errors" rule explicitly forbids informal phrasing like "Uh-oh" or "There seems to be a problem." The skill mandates that errors be rewritten into the cause-fix format before reaching the user.

agents/gemini.toml — Model-Specific Reinforcement

The Gemini agent configuration at skills/i-have-adhd/agents/gemini.toml (line 17) duplicates this rule, ensuring the matter-of-fact error handling applies consistently across Google's Gemini models.

Correct vs. Incorrect Error Reporting

Example 1: Correct Format (Skill-Compliant)

Test fails at `auth.spec.ts:42`: expected 200, got 401.
Cause: missing Authorization header.
Fix: add `Authorization: Bearer ${token}` to the request.

This message includes:

• Specific location (auth.spec.ts:42)
• Explicit cause (missing header)
• Actionable fix (exact header to add)

Example 2: Incorrect Format (Skill Rejected)

Uh oh, the test is failing. There seems to be a problem with the auth header.

The skill automatically rewrites this into the Example 1 format. The original violates the rule on three counts: emotional opener ("Uh oh"), vague phrasing ("there seems to be"), and no clear next step.

Why This Matters for ADHD Accessibility

The strict error handling in i-have-adhd addresses common ADHD challenges:

• Decision paralysis — ambiguous errors force users to interpret multiple possibilities; the cause-fix format presents exactly one path forward
• Working memory load — emotional language and apologies consume attention without adding information
• Task initiation — explicit "Fix" instructions reduce the friction of getting started on remediation

Implementation Across Agent Types

File	Role in Error Handling
skills/i-have-adhd/SKILL.md	Defines the canonical error format rule (lines 98-104)
skills/i-have-adhd/agents/gemini.toml	Reinforces rule for Gemini models (line 17)
skills/i-have-adhd/agents/openai.yaml	Activates skill interface for OpenAI-based responses

Note that agents/openai.yaml establishes the skill's presence for OpenAI models but does not duplicate the error rule itself—the specification in SKILL.md serves as the single source of truth.

Summary

• The i-have-adhd skill enforces matter-of-fact error handling for all AI responses
• Errors must follow a strict cause-fix format with no emotional or ambiguous language
• The rule originates in SKILL.md (lines 98-104) and is mirrored in agents/gemini.toml (line 17)
• Incorrect formats like "Uh-oh" or "There seems to be a problem" are automatically rewritten
• This design prioritizes actionable clarity over conversational tone for ADHD accessibility

Frequently Asked Questions

What happens if an AI generates an error that doesn't follow the format?

The i-have-adhd skill intercepts and rewrites the error. As shown in the analysis, a message like "Uh oh, the test is failing" gets transformed into a structured report with explicit cause and fix components before reaching the user.

Does the error-handling rule apply to all AI models in the skill?

The rule is defined centrally in SKILL.md and explicitly reinforced for Gemini in agents/gemini.toml. OpenAI model behavior is governed through the skill interface in agents/openai.yaml, which activates the same underlying specification.

Why can't AI errors include apologies or empathetic language?

The skill prioritizes cognitive efficiency over emotional rapport. For users with ADHD, phrases like "I'm sorry" or "That must be frustrating" add processing overhead without actionable information. The cause-fix format respects user time and attention.

Can I customize the error format for my own deployment?

The skill uses declarative configuration files. While the current implementation enforces a rigid structure, the SKILL.md specification and agent configs are standard files that can be forked and modified according to the repository's open-source license.

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