Error Reporting in i-have-adhd Mode: Tone and Content Guidelines

Error reporting in i-have-adhd mode follows a strict "matter-of-fact" style that eliminates apologetic phrasing and focuses on stating the cause, presenting the fix, and keeping messages concise.

The i-have-adhd mode, developed in the ayghri/i-have-adhd repository, provides a structured approach to communicating failures. Designed specifically for developers with ADHD, this mode strips away emotional noise that could distract from taking the next concrete step.

The Core Rule: Matter-of-Fact Tone for Errors

According to the skill definition in skills/i-have-adhd/SKILL.md lines 96-101, error reporting forbids any of the following:

• "Uh oh" or "Oh no" interjections
• "There seems to be a problem" hedging language
• Preambles, apologies, or closing pleasantries
• Dramatic or emotionally loaded phrasing

Instead, every error message must adhere to a three-part structure.

The Three-Part Error Structure

1. State the Cause

Pinpoint the exact failure point. This could be:

• A specific test failure line (e.g., auth.spec.ts:42)
• A missing header or configuration value
• A thrown exception with its message

2. Present the Fix

Provide the concrete change required: a command to run, a code snippet to add, or a configuration update to make.

3. Keep It Concise

No fluff. The message should be immediately actionable without reading past emotional padding.

Error Reporting Examples in i-have-adhd Mode

Example 1: Reporting a Failing Test

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

Notice the absence of "Uh oh, your test failed!" or similar. The response moves directly from failure location → root cause → resolution.

Example 2: Handling Thrown Exceptions

The runtime implementation in extensions/i-have-adhd.ts formats errors according to this specification:

try {
  // …code that may throw
} catch (error) {
  const reason = error instanceof Error ? error.message : String(error);
  // ✅ Matter-of-fact error output
  console.error(`Operation failed: ${reason}`);
}

The output Operation failed: ${reason} follows the prescribed tone. Compare this to the discouraged approach—which would prepend "Uh oh" or "Something went wrong" before the reason.

Example 3: CLI-Level Error Interpretation

When encountering standard CLI errors like:

npm ERR! code ENOENT
npm ERR! syscall open
npm ERR! path /some/missing/file.js

The i-have-adhd mode reformats this as:

Cause: the file does not exist at the supplied path.
Fix: verify the path or create the missing file.

Key Files Defining Error Reporting Behavior

File	Purpose	Link
skills/i-have-adhd/SKILL.md	Defines the matter-of-fact error-reporting tone and all output rules	SKILL.md
extensions/i-have-adhd.ts	Implements runtime behavior; catches and formats errors per the skill	i-have-adhd.ts
README.md	Overview and quick reference to the rule set	README.md

Why This Tone Matters for ADHD Accessibility

The architectural intent behind i-have-adhd error reporting is cognitive load reduction. Emotional phrasing—however well-intentioned—creates additional processing overhead. For developers with ADHD, this overhead can:

• Trigger distraction or task-switching
• Delay the path to resolution
• Introduce unnecessary anxiety

By presenting errors as straightforward factual statements, the mode respects the user's time and attention.

Summary

• Matter-of-fact tone is mandatory—all apologetic or dramatic language is prohibited
• Three-part structure: state cause → present fix → stay concise
• Key implementation resides in skills/i-have-adhd/SKILL.md and extensions/i-have-adhd.ts
• Design goal: minimize cognitive load for developers with ADHD by removing emotional noise

Frequently Asked Questions

What words or phrases are explicitly banned in i-have-adhd error reporting?

The skill explicitly forbids "Uh oh", "Oh no", "There seems to be a problem", and similar apologetic or dramatic phrasing. These are documented in the "Matter-of-fact tone for errors" section of skills/i-have-adhd/SKILL.md.

How does i-have-adhd mode differ from standard error reporting?

Standard error reporting often includes hedging language, apologies, or emotional cushioning. The i-have-adhd mode strips all of this away to present only: what failed, why it failed, and how to fix it. This design specifically supports sustained focus for users with ADHD.

Where is the error formatting logic implemented in the codebase?

The runtime implementation is located in extensions/i-have-adhd.ts, which catches errors and formats them according to the rules defined in skills/i-have-adhd/SKILL.md. The skill file contains the canonical specification; the extension file contains the executable behavior.

Can I use i-have-adhd mode for non-ADHD team members?

Yes. While designed for ADHD accessibility, the matter-of-fact approach benefits any developer who prefers direct, actionable communication without conversational overhead. The mode functions as a universal clarity enhancement.

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