# How Should Errors Be Handled According to Rule 8 (Matter-of-Fact Errors)

> Learn how Rule 8 handles matter-of-fact errors by clearly stating the failure cause and exact fix. Reduce cognitive load with precise, direct error messaging.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: how-to-guide
- Published: 2026-08-21

---

**Rule 8 requires error messages to directly state the precise cause of failure and the exact fix, eliminating soft language or emotive interjections to reduce cognitive load for readers with ADHD.**

The **i-have-adhd** skill repository establishes strict communication guidelines designed to minimize working-memory demands. According to Rule 8's matter-of-fact error handling protocol, developers must replace apologetic or vague phrasing with immediate, actionable technical details. This approach ensures that error messages function as compact instructions rather than emotional barriers.

## Rule 8 Definition in SKILL.md

The formal specification resides in [[`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md#L98) under the section "### 8. Matter-of-fact tone for errors". This file defines the complete rule set governing how the skill generates and formats error communications.

## Core Requirements for Rule 8 Matter-of-Fact Errors

### Eliminate Soft Language and Emotive Interjections

Rule 8 explicitly forbids phrases like "Uh oh," "Oh no," or "There seems to be a problem." These expressions add cognitive overhead without providing technical value.

### State the Precise Cause

Error messages must identify the specific file, line number, or condition that triggered the failure. This precision allows readers to locate the issue immediately without parsing extraneous context.

### Provide the Concrete Fix

Every error message must conclude with the exact code change, configuration tweak, or command required to resolve the issue. This transforms the error from a problem statement into an executable solution.

## Rule 8 Error Handling Examples

### Test Failure Scenario

**Incorrect (violates Rule 8):**

```text
Uh oh, the test is failing. There seems to be an issue…

```

**Correct (Rule 8 compliant):**

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

```

### Missing Environment Variable

**Incorrect:**

```text
Oh no, we can't find the API key.

```

**Correct:**

```text
Missing environment variable API_KEY in .env. Fix: add API_KEY=your_key_here to the .env file and reload the process.

```

### Database Migration Error

**Incorrect:**

```text
There seems to be a problem applying the migration.

```

**Correct:**

```text
Migration error: column `user_id` already exists in table `orders`. Cause: duplicate migration run. Fix: rollback the last migration (`npm run migrate:down`) and remove the duplicated file.

```

## Implementation and Enforcement

The matter-of-fact error style is enforced through multiple mechanisms in the repository. The [[`evals/rubric.md`](https://github.com/ayghri/i-have-adhd/blob/main/evals/rubric.md)](https://github.com/ayghri/i-have-adhd/blob/main/evals/rubric.md) defines evaluation criteria that check for compliance with Rule 8 during skill assessment. Meanwhile, [[`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts)](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) implements the runtime behavior where these error messages are generated, ensuring that all outputs adhere to the strict formatting requirements defined in the skill definition.

## Summary

- Rule 8 mandates direct, unemotional error reporting that states causes and fixes explicitly.
- The specification lives in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) at line 98 under the matter-of-fact tone section.
- Error messages must exclude soft language like "Uh oh" or "There seems to be a problem."
- Each error must specify the exact file, line, or condition causing the failure.
- Every message must provide the precise command or code change needed to resolve the issue.

## Frequently Asked Questions

### What specific phrases does Rule 8 prohibit in error messages?

Rule 8 prohibits soft-language and emotive interjections such as "Uh oh," "Oh no," and "There seems to be a problem." The rule requires replacing these with immediate technical facts about the failure state.

### Where is Rule 8 formally documented in the i-have-adhd repository?

Rule 8 is formally documented in [[`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md#L98) under the heading "### 8. Matter-of-fact tone for errors".

### How does Rule 8 reduce cognitive load for developers with ADHD?

By eliminating emotional preamble and providing the exact cause and fix in a single sentence, Rule 8 reduces working-memory demands. Readers can act immediately without processing apologetic language or guessing at solutions.

### How is compliance with Rule 8 enforced in the codebase?

Compliance is enforced through [[`evals/rubric.md`](https://github.com/ayghri/i-have-adhd/blob/main/evals/rubric.md)](https://github.com/ayghri/i-have-adhd/blob/main/evals/rubric.md), which defines evaluation criteria for the matter-of-fact style, and implemented in [[`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts)](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts), which generates Rule 8-compliant error messages at runtime.