# How i-have-adhd Handles Errors: Validation, Aggregation, and Matter-of-Fact Reporting

> Discover how i-have-adhd manages errors with input validation, duplicate detection, and clear, aggregated reporting for a streamlined experience.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: deep-dive
- Published: 2026-08-04

---

**The i-have-adhd skill centralizes error handling in [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py) through deterministic input validation, duplicate detection, and aggregated error reporting that maintains a concise, matter-of-fact tone without emotional filler.**

The `ayghri/i-have-adhd` repository implements a defensive **i-have-adhd error handling** strategy designed to catch data integrity issues before processing begins. All validation logic resides in the evaluation script, ensuring that malformed inputs, duplicate identifiers, and type mismatches trigger immediate, actionable feedback. This approach aligns with the skill's documented philosophy of providing technical guidance without apologetic or emotional language.

## Input Validation and Duplicate Detection in scripts/run_evals.py

The `validate_cases` function in [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py) serves as the primary gatekeeper for evaluation data. It inspects every case for required fields, proper Python types, and logical consistency, including checks for non-empty IDs, allowed risk levels, and non-empty criteria lists.

While iterating through cases, the function maintains a set of seen identifiers to detect duplicates. If an ID appears twice, the function records a specific *“Duplicate case id”* error alongside any other validation failures.

```python
from scripts.run_evals import validate_cases

cases = [
    {"id": "case1", "risk": "low", "criteria": ["criterion"]},
    {"id": "", "risk": "medium", "criteria": []},
    {"id": "case1", "risk": "high", "criteria": ["c"]}
]

errors = validate_cases(cases)
if errors:
    raise ValueError("\n".join(errors))

```

Executing this code raises a single `ValueError` containing a newline-separated list of all detected issues:

```text
Case 1: id must be a non-empty string
Case 1: criteria must be a non-empty list
Duplicate case id: case1

```

## Error Aggregation and CLI Feedback

Rather than failing fast on the first problem, the validation logic aggregates all detected issues into a comprehensive list. This **aggregated error reporting** allows developers to see the full set of validation failures in a single execution, reducing iterative debugging cycles.

For command-line usage, the script leverages Python's `argparse` module to enforce valid subcommands. When users invoke an unsupported command, the parser calls `parser.error("unknown command")`, which prints a concise usage message to `stderr` and exits with status code 2.

```bash
$ python -m scripts.run_evals unknown_cmd
usage: run_evals.py [-h] {run,validate}
run_evals.py: error: unknown command

```

This deterministic exit behavior ensures that shell scripts and CI pipelines can reliably detect invocation errors without parsing ambiguous output.

## Continuous Integration Error Reporting

The repository surfaces pipeline failures visibly using GitHub Actions annotations. The workflow defined in [`.github/workflows/plugin-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/plugin-load-check.yml) employs the `::error::` syntax to highlight critical failures directly in the GitHub UI, ensuring that validation errors in [`run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/run_evals.py) are immediately apparent to developers.

```yaml
- name: Load plugin
  run: |
    python -m scripts.run_evals validate
  if: failure()
- echo "::error::plugin failed to load; see claude plugin list output above"

```

When the validation script detects malformed cases or duplicate IDs, this annotation appears prominently in the workflow logs, linking directly to the line of failure.

## Matter-of-Fact Error Philosophy

According to [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md), the skill adopts a **matter-of-fact tone for errors**. This documentation explicitly prohibits emotional filler, apologies, or hedging language in error messages. The implementation in [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py) adheres to this standard by returning direct, technical descriptions of validation failures without conversational padding.

For example, the error message reads *“Duplicate case id: case1”* rather than *“Sorry, it seems like there might be a duplicate case ID.”* This precision reduces cognitive load and ensures users receive only actionable technical information.

## Summary

- **Centralized validation** occurs in [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py) through the `validate_cases` function, which enforces required fields, valid types, and logical consistency.
- **Duplicate detection** maintains a set of seen IDs during iteration, reporting duplicates as distinct error entries.
- **Aggregated reporting** collects all validation failures into a single `ValueError` with newline-separated messages, enabling comprehensive debugging.
- **CLI integration** uses `argparse` with `parser.error()` to provide immediate feedback and non-zero exit codes for invalid commands.
- **CI visibility** leverages GitHub Actions `::error::` annotations in [`.github/workflows/plugin-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/plugin-load-check.yml) to surface failures prominently.
- **Communication style** follows a matter-of-fact tone documented in [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md), eliminating emotional language from all error output.

## Frequently Asked Questions

### How does i-have-adhd validate evaluation cases?

The `validate_cases` function in [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py) inspects each case for non-empty string IDs, allowed risk level values, and non-empty criteria lists. It aggregates any violations into a list of human-readable strings, returning them for batch reporting rather than raising exceptions individually.

### What happens when duplicate case IDs are detected?

During iteration over the case list, the validation logic maintains a set of previously encountered IDs. If a duplicate identifier is found, the function appends a *“Duplicate case id”* message to the error list. This check runs alongside other validations, ensuring all issues are reported simultaneously in the final `ValueError`.

### How are errors formatted in the CLI output?

Command-line parsing errors use Python's `argparse` error handling, which prints a usage summary and specific error message to `stderr` before exiting with status code 2. Validation errors raised as `ValueError` display newline-separated lists of all detected issues when caught and printed by the calling code, following the format *“Case {n}: {description}”*.

### What is the error handling philosophy of the i-have-adhd skill?

As documented in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md), the skill maintains a **matter-of-fact tone for errors**. This philosophy requires that all error output remain directive and concise, focusing solely on the technical issue and resolution path without apologetic or emotional language.