Matter-of-Fact Errors Rule: How to Format Error Messages in i-have-adhd

The matter-of-fact errors rule requires stating the cause and fix of an error directly without apologetic or vague language such as "Uh oh" or "There seems to be a problem."

The matter-of-fact errors rule is a core guideline in the ayghri/i-have-adhd repository that governs how AI agents report failures. As one of ten foundational rules defined in the skill specification, it mandates a direct, factual tone that eliminates cognitive overhead for readers who need to act on error information immediately.

What Is the Matter-of-Fact Errors Rule?

According to the canonical specification in skills/i-have-adhd/SKILL.md (lines 96–102), the matter-of-fact errors rule mandates that every error report must be presented directly, without any apologetic or vague language. This guideline ensures that when the system encounters a failure, it communicates only the essential diagnostic information required to resolve the issue.

The rule is explicitly referenced as Rule 8 in the runtime configuration at skills/i-have-adhd/agents/gemini.toml, ensuring consistent enforcement across different AI runtimes including Gemini and Claude.

Core Requirements for Error Message Formatting

Compliant error messages must follow a strict two-part structure that prioritizes actionability over explanation.

State the Cause

Error messages must clearly identify what went wrong and where the failure occurred. This includes specific file paths, line numbers, and the technical nature of the error.

Provide the Fix

Immediately following the cause, the message must deliver a concrete, actionable solution. This could be a specific command to run, a code change to implement, or a configuration adjustment.

Prohibited Phrases and Language Patterns

The specification explicitly forbids filler phrases that create emotional distance or vagueness:

• "Uh oh"
• "Oh no"
• "There seems to be a problem"
• Any hedging language that implies uncertainty rather than certainty

Matter-of-Fact Errors Rule Examples

Here are concrete examples comparing non-compliant and compliant error messages for common development scenarios.

Test Failure Scenario:

❌ Non-compliant:

Uh oh, the test is failing. There seems to be an issue…

✅ Compliant:

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

Missing File Scenario:

❌ Non-compliant:

Oh no, I can't find the config file.

✅ Compliant:

File `config/app.json` not found (ENOENT). **Cause:** file was never created. **Fix:** create the file with the required JSON structure or run `npm run init-config`.

Build Error Scenario:

❌ Non-compliant:

There seems to be a problem with the build step.

✅ Compliant:

Build fails at `webpack.config.js:27`: `Module not found: 'react'`. **Cause:** missing dependency. **Fix:** run `npm install react` and retry the build.

Implementation Across Runtimes

The matter-of-fact errors rule is enforced across multiple AI runtimes through configuration files. In skills/i-have-adhd/agents/gemini.toml, the rule is referenced as Rule 8 ("Matter-of-fact errors"), ensuring that the Gemini runtime adheres to the same factual error reporting standard defined in the canonical SKILL.md specification.

Summary

• The matter-of-fact errors rule is defined in skills/i-have-adhd/SKILL.md (lines 96–102) as one of ten core guidelines in the i-have-adhd skill.
• Prohibited phrases include "Uh oh," "Oh no," and "There seems to be a problem."
• Required structure includes stating the Cause (what went wrong and where) and the Fix (concrete resolution steps).
• Runtime enforcement occurs through configuration files like skills/i-have-adhd/agents/gemini.toml, which references this as Rule 8.

Frequently Asked Questions

What specific phrases violate the matter-of-fact errors rule?

The specification explicitly bans apologetic or vague openers including "Uh oh," "Oh no," and "There seems to be a problem." These phrases add emotional distance without providing diagnostic value, forcing the reader to process unnecessary hedging language before reaching actionable information.

Where is the matter-of-fact errors rule defined in the i-have-adhd repository?

The rule is canonically defined in skills/i-have-adhd/SKILL.md at lines 96–102, and referenced as Rule 8 in runtime configurations such as skills/i-have-adhd/agents/gemini.toml. Together these files ensure consistent enforcement across different AI runtimes.

How should a compliant error message be structured?

A compliant message must contain two components: the Cause, identifying the specific location and nature of the error (e.g., file paths and line numbers), and the Fix, providing an actionable command or code change that resolves the issue. Both elements must be stated immediately without filler text.

Does the matter-of-fact errors rule apply to all AI runtimes using this skill?

Yes, the rule is enforced across all configured runtimes. The gemini.toml configuration explicitly references Rule 8 to ensure the Gemini runtime adheres to the same factual error reporting standard as other implementations, maintaining consistency regardless of which AI model processes the request.

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