# Matter-of-Fact Errors Rule: How to Format Error Messages in i-have-adhd > Master the matter-of-fact errors rule for i-have-adhd. Learn to format clear, actionable error messages that directly state the cause and fix. Improve user experience now. - Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd) - Tags: how-to-guide - Published: 2026-08-26 --- **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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) specification. ## Summary - The matter-of-fact errors rule is defined in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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.