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

The i-have-adhd skill centralizes error handling in 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 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.

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:

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.

$ 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 employs the ::error:: syntax to highlight critical failures directly in the GitHub UI, ensuring that validation errors in run_evals.py are immediately apparent to developers.

- 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, 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 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 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 to surface failures prominently.
• Communication style follows a matter-of-fact tone documented in 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 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, 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.

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