Expected Format for Error Messages in i-have-adhd: The Matter-of-Fact Pattern

The i-have-adhd skill enforces a strict, matter-of-fact error message format that eliminates apologetic language, states the precise cause including file locations and expected versus actual values, and provides immediate actionable fixes.

The i-have-adhd repository defines a rigorous communication protocol designed for developers who require concise, actionable feedback without cognitive overhead. According to the skill definition in skills/i-have-adhd/SKILL.md, all error messages must follow a specific structural pattern that prioritizes technical accuracy over casual conversation, ensuring every failure report contains exactly the information needed for resolution.

The Core Error Message Structure in i-have-adhd

According to Rule 8 in skills/i-have-adhd/SKILL.md (lines 96-101), error messages must adhere to a rigid three-part structure:

1. Failure description with location: Identify precisely what failed and where it occurred
2. Cause statement: Explain the technical reason concisely without filler language
3. Fix instruction: Provide exact code snippets or commands to resolve the issue immediately

The canonical syntax follows this pattern:

<Brief description of the failure> at <location>: <expected>, got <actual>.
Cause: <concise explanation>.
Fix: <exact change or command>.

For example, the skill documentation demonstrates:

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

Prohibited Language Patterns

The skill explicitly forbids informal or apologetic phrasing that adds noise without technical value. According to lines 96-101 of the skill definition, developers must eliminate expressions such as "Uh oh", "Oh no", or "There seems to be a problem." These phrases consume mental bandwidth while contributing nothing to the solution.

Required Components of Valid Error Messages

Neutral Tone Without Apologies

Error reporting in i-have-adhd maintains a strictly neutral, actionable tone. The communication focuses exclusively on what went wrong and how to resolve it, eliminating social padding that distracts from the technical solution.

Precise Cause Documentation

Every error must specify the exact location of the failure, including file paths and line numbers where applicable. The message must explicitly contrast expected behavior against actual results using the format "expected X, got Y" to eliminate ambiguity about the failure mode.

Immediate Actionable Fixes

The fix section requires concrete implementation details rather than vague suggestions. Instead of recommending users "check the configuration," the format demands specific code snippets or exact commands, such as add Authorization: Bearer ${token} to the request or remove the trailing comma.

Practical Code Examples

Below are implementations of the i-have-adhd error format across different contexts:

// API request failure
console.error(
  "Request to /api/login failed: expected 200, got 403.\n" +
  "Cause: user account is disabled.\n" +
  "Fix: reactivate the account in the admin dashboard."
);

// Build step error
console.error(
  "Webpack build error at src/app.js:12: Unexpected token.\n" +
  "Cause: stray comma after the last property.\n" +
  "Fix: remove the trailing comma."
);

# CLI command failure

echo "npm install failed: ERR! code ENOENT, no such file or directory."
echo "Cause: missing package.json in the project root."
echo "Fix: run npm init to create a package.json before installing dependencies."

Agent Configuration Reinforcement

The matter-of-fact error tone is further enforced in skills/i-have-adhd/agents/gemini.toml at line 17, which configures the Gemini agent to maintain the strict error reporting standards defined in the skill file. This ensures consistency across all automated implementations of the protocol.

Summary

• Eliminate casual language: Remove "uh oh", "sorry", and apologetic phrasing from all error output
• Follow the three-part structure: Failure at Location: expected X, got Y. Cause: Z. Fix: W.
• Provide specifics: Include exact file paths, line numbers, and copy-pasteable code snippets in your fixes
• Maintain neutrality: Focus solely on technical facts and immediate resolution steps

Frequently Asked Questions

Why does i-have-adhd prohibit apologetic error messages?

The skill prioritizes cognitive efficiency for developers with ADHD. Apologetic language consumes working memory without contributing to the solution, whereas matter-of-fact statements deliver critical technical information immediately, reducing the mental overhead required to parse the error.

Can I include stack traces in i-have-adhd error messages?

While stack traces provide useful location data, they must supplement—not replace—the structured Cause and Fix sections. The format requires explicit cause statements and concrete fixes to meet the accessibility standards defined in skills/i-have-adhd/SKILL.md.

How do I format errors when the exact location is unclear?

Maintain the three-part structure even without specific file paths: state what failed, contrast expected versus actual behavior, explain the underlying cause, and provide the concrete fix. For example: "Database connection failed: expected successful handshake, got timeout. Cause: network latency exceeds threshold. Fix: increase connection timeout to 5000ms in config.yml."

Does the gemini.toml configuration override the SKILL.md error format?

No, skills/i-have-adhd/agents/gemini.toml reinforces the standards defined in the skill file. Line 17 specifically ensures the Gemini agent adheres to the matter-of-fact tone requirement, creating consistency across all implementations of the i-have-adhd communication protocol.

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