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

> Learn the matter-of-fact tone and content guidelines for error reporting in i-have-adhd mode. State causes, fixes, and keep messages concise for effective bug reporting.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: best-practices
- Published: 2026-09-02

---

**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](https://github.com/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`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) [lines 96-101](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md#L96-L101), 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`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) formats errors according to this specification:

```typescript
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`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) | Defines the matter-of-fact error-reporting tone and all output rules | [SKILL.md](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) |
| [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) | Implements runtime behavior; catches and formats errors per the skill | [i-have-adhd.ts](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) |
| [`README.md`](https://github.com/ayghri/i-have-adhd/blob/main/README.md) | Overview and quick reference to the rule set | [README.md](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) and [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts), which catches errors and formats them according to the rules defined in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/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.