The i‑have‑ADHD Approach to Matter‑of‑Fact Errors: A Technical Breakdown

The i‑have‑ADHD skill enforces Rule 8, which requires error messages to state the cause first, provide an immediate fix, and eliminate all emotive language to minimize distraction for readers with ADHD.

The open‑source repository ayghri/i‑have‑adhd defines a communication framework optimized for neurodivergent cognition. Its specification for matter‑of‑fact errors appears as Rule 8 in skills/i‑have‑adhd/SKILL.md, establishing strict formatting guidelines that prioritize clarity and actionability over traditional error messaging.

Understanding Rule 8: Matter‑of‑Fact Tone for Errors

Rule 8 in SKILL.md establishes a three‑pillar framework for error reporting. Unlike conventional error handling that often includes apologetic or alarming phrasing, this approach treats failures as neutral events requiring direct remediation.

The rule mandates that every error message must:

• Avoid emotional signifiers that increase cognitive load
• Present the technical cause before remediation steps
• Provide an immediately executable fix

Key Requirements for Matter‑of‑Fact Error Messages

Eliminate Emotive Language

According to the specification in skills/i‑have‑adhd/SKILL.md, error messages must exclude phrases such as “Uh oh,” “Oh no,” or “There seems to be a problem.” These expressions add parsing overhead without contributing diagnostic value. Instead, the format opens with the specific location and nature of the failure.

Cause‑First Structure

The rule requires stating the technical cause immediately after identifying the failure location. This structure aligns with how ADHD‑optimized cognition processes information: identifying what broke before determining how to repair it.

Standard format:

[Location]: [Expected outcome], [Actual outcome]. Cause: [Root reason]. Fix: [Corrective action].

Concise, Actionable Fixes

Every error message must conclude with a specific, executable fix. Vague suggestions like “try again” or “check settings” violate the specification. The fix should contain exact syntax, file paths, or command modifications when applicable.

Implementation Examples

The repository provides reference implementations demonstrating the matter‑of‑fact pattern across different languages.

Python Error Formatter

The following function in skills/i‑have‑adhd/SKILL.md generates compliant error strings:

def format_error(location: str, expected: int, got: int, cause: str, fix: str) -> str:
    """
    Returns a concise, matter‑of‑fact error message.
    """
    return (
        f"Test fails at {location}: expected {expected}, got {got}. "
        f"Cause: {cause}. Fix: {fix}."
    )

# Example usage

msg = format_error(
    location="auth.spec.ts:42",
    expected=200,
    got=401,
    cause="missing auth header",
    fix="add `Authorization: Bearer ${token}` to the request"
)
print(msg)

Output:

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

CLI Error Reporting

For shell environments, the specification recommends wrapping commands with matter‑of‑fact failure handlers:

#!/usr/bin/env bash

# Run a command and report any failure matter‑of‑fact

run_and_report() {
    "$@"
    status=$?
    if [[ $status -ne 0 ]]; then
        echo "Command \`$*\` exited with status $status. Cause: non‑zero exit code. Fix: verify arguments and retry."
        exit $status
    fi
}

# Example usage

run_and_report npm test -- auth.spec.ts

When npm test fails, this outputs:

Command `npm test -- auth.spec.ts` exited with status 1. Cause: non‑zero exit code. Fix: verify arguments and retry.

Source Files and Configuration

The matter‑of‑fact error rule is implemented across three key files in the ayghri/i‑have‑adhd repository:

• skills/i‑have‑adhd/SKILL.md – Contains the canonical Rule 8 definition and formatting requirements for error messages.
• README.md – Provides high‑level documentation linking to the skill rules and explaining the rationale behind ADHD‑optimized communication.
• plugin.json – Registers the skill with Claude/Codex plugin systems, ensuring Rule 8 constraints are applied at runtime.

Why Matter‑of‑Fact Errors Reduce Cognitive Load

Traditional error messaging often interlears emotional context with technical details, requiring readers to filter relevant data from social cues. The i‑have‑ADHD approach removes this filtering step by presenting only actionable facts. For developers with ADHD, this reduces the executive function required to transition from error detection to error resolution.

Summary

• Rule 8 in skills/i‑have‑adhd/SKILL.md mandates a strict format for all error reporting.
• Emotive language is prohibited; messages must begin with location and technical specifics.
• Structure follows the pattern: Location → Expected vs. Actual → Cause → Fix.
• Reference implementations are provided in Python and Bash for immediate adoption.
• Configuration is centralized in SKILL.md, README.md, and plugin.json.

Frequently Asked Questions

What defines a matter‑of‑fact error in the i‑have‑ADHD specification?

A matter‑of‑fact error follows Rule 8 in SKILL.md by stating the failure location, expected versus actual results, the root cause, and an immediate fix—without using emotional language or apologetic phrasing. This structure ensures readers receive only actionable technical information.

Where is Rule 8 documented in the repository?

Rule 8 is documented in skills/i‑have‑adhd/SKILL.md under the heading “8. Matter‑of‑Fact Tone for Errors.” This file serves as the primary specification for the skill’s output constraints.

Why does the specification ban phrases like “Uh oh” or “Oh no”?

These phrases constitute emotive language that increases cognitive load without contributing diagnostic value. The i‑have‑ADHD framework prioritizes executive function preservation, requiring that all communication bytes convey actionable technical data.

How does the plugin system enforce these error formatting rules?

The plugin.json file registers the skill with Claude/Codex systems, ensuring that Rule 8 constraints are applied at runtime. When the skill generates error output, it must conform to the matter‑of‑fact structure defined in SKILL.md to pass validation.

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