# Handling Errors with a Matter-of-Fact Tone in i-have-adhd: A Complete Implementation Guide

> Learn to handle errors with a matter-of-fact tone in the i-have-adhd skill. This guide details plain, factual error reporting for direct solutions.

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

---

**The i-have-adhd skill mandates that every error message must state the cause and fix plainly, strictly prohibiting apologetic or emotional language such as "Uh oh" or "There seems to be a problem" in favor of direct, factual reporting.**

The `ayghri/i-have-adhd` repository enforces a rigorous error-handling strategy designed to reduce cognitive load for users with ADHD. Handling errors with a matter-of-fact tone in i-have-adhd means all validation failures, runtime exceptions, and CLI outputs deliver unemotional, actionable information without unnecessary preamble. This architectural decision is codified in the project's skill definition and implemented consistently across the Python evaluation framework.

## Where the Matter-of-Fact Error Rule Is Defined

The foundational rule governing error communication lives 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)** at **lines 98-102**. According to the ayghri/i-have-adhd source code, the guideline explicitly states: "Never use 'Uh oh,' 'Oh no,' or 'There seems to be a problem.' State cause and fix."

This specification applies to every error surface within the repository, from configuration validation to runtime execution failures. The rule ensures that **error messages** remain deterministic and machine-parseable, making them suitable for CI pipelines and automated tooling.

## How Error Handling Is Implemented in run_evals.py

The **[[`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py)](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py)** file contains the central implementation of the matter-of-fact error strategy. The script follows a three-phase pattern: validation collection, stderr output, and exception raising.

### Validating Cases with Plain Error Strings

The **`validate_cases`** function (lines 59-79) aggregates all configuration problems into a list of plain strings before displaying them. This approach avoids interrupting the user with multiple emotional alerts and instead presents a complete, bulleted summary of issues.

```python
def validate_cases(cases: list[dict[str, Any]]) -> list[str]:
    errors: list[str] = []
    seen: set[str] = set()
    required = {"id", "category", "prompt", "risk", "criteria"}
    for index, case in enumerate(cases, start=1):
        missing = sorted(required - set(case))
        if missing:
            errors.append(f"Case {index}: missing fields: {', '.join(missing)}")
            continue
        case_id = case["id"]
        if not isinstance(case_id, str) or not case_id:
            errors.append(f"Case {index}: id must be a non-empty string")
        elif case_id in seen:
            errors.append(f"Duplicate case id: {case_id}")
        else:
            seen.add(case_id)
        if case["risk"] not in {"low", "medium", "high"}:
            errors.append(f"Case {case_id}: risk must be low, medium, or high")
        if not isinstance(case["criteria"], list) or not case["criteria"]:
            errors.append(f"Case {case_id}: criteria must be a non-empty list")
    return errors

```

Each error string follows the format `Case {identifier}: {problem description}`, providing the exact location and nature of the failure without decorative language.

### Printing Factual Errors to stderr

When validation completes, the CLI outputs errors using a simple **"ERROR:"** prefix to standard error. Lines 345-346 implement this behavior:

```python
if errors:
    for error in errors:
        print(f"ERROR: {error}", file=sys.stderr)
    return 1

```

The prefix is **factual and consistent**, containing no "Oops" or "Sorry" qualifiers that might obscure the technical content for automated parsers.

### Raising Concise Runtime Exceptions

For execution failures, the script raises **`RuntimeError`** with messages that describe the condition and include captured detail, but never add emotional framing. Lines 80-82 demonstrate this pattern:

```python
if completed.returncode:
    detail = completed.stderr.strip() or completed.stdout.strip()
    raise RuntimeError(
        f"Runner failed after {args.retries + 1} attempts "
        f"({shlex.join(invocation[:-1])}):\n{detail}"
    )

```

The exception text states the failure condition (`Runner failed after … attempts`) and includes the specific command and output, maintaining the matter-of-fact tone required by the skill.

## Complete Error Handling Workflow

The architectural flow ensures consistent tone across all failure modes:

1. **Input validation** – `validate_cases` checks for required fields (`id`, `category`, `prompt`, `risk`, `criteria`), duplicate IDs, valid risk values, and non-empty criteria lists.
2. **Error aggregation** – All problems accumulate in the `errors` list as plain strings.
3. **Early termination** – If any errors exist, `run_evaluations` raises a `ValueError` that propagates to the CLI, causing a non-zero exit code.
4. **User-visible output** – The CLI prints each error line prefixed with `ERROR:` to stderr, keeping output machine-readable and deterministic.

This design guarantees that **every error** adheres to the **matter-of-fact style** defined in the skill configuration.

## Summary

- The matter-of-fact error rule is defined in [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) lines 98-102, prohibiting emotional language like "Uh oh" or "There seems to be a problem."
- The `validate_cases` function in [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py) (lines 59-79) collects validation errors as plain, descriptive strings without preamble.
- Error output uses a factual "ERROR:" prefix printed to stderr (lines 345-346), avoiding decorative or apologetic language.
- Runtime failures raise `RuntimeError` with concise technical descriptions (lines 80-82), stating the cause and including relevant detail without emotional framing.
- This approach ensures error messages remain parseable by downstream CI tools and cognitively accessible for users with ADHD.

## Frequently Asked Questions

### What phrases are prohibited in i-have-adhd error messages?

According to the skill definition in [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md), developers must never use phrases such as "Uh oh," "Oh no," or "There seems to be a problem." The guideline requires stating the cause and fix directly, ensuring messages remain unemotional and actionable.

### How does run_evals.py validate case configurations?

The `validate_cases` function at lines 59-79 in [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py) checks each case for required fields (`id`, `category`, `prompt`, `risk`, `criteria`), validates that risk values are one of "low," "medium," or "high," ensures criteria lists are non-empty, and detects duplicate IDs. It accumulates all failures in a list of plain strings before returning them to the caller.

### Where are errors printed in the i-have-adhd codebase?

Errors are printed to standard error (stderr) in the main execution block of [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py) at lines 345-346. Each error line uses the format `ERROR: {message}`, providing a consistent, machine-readable prefix that contains no emotional qualifiers.

### Why does the i-have-adhd skill enforce unemotional error reporting?

The matter-of-fact tone reduces cognitive load for users with ADHD by eliminating ambiguous or anxiety-inducing language that might distract from the technical solution. Plain error statements allow users to quickly identify the problem and required fix without processing unnecessary social pleasantries or alarmist phrasing.