i-have-adhd Rules for Debugging and Error Handling: Rule 8 and the Debug Spiral

The i-have-adhd rules for debugging and error handling enforce a direct, emotionless reporting style and mandate a "debug spiral" protocol that halts repetitive fixes after three failed attempts to surface hidden assumptions.

The ayghri/i-have-adhd repository provides a constrained communication framework designed to minimize cognitive overhead during technical work. Understanding the i-have-adhd rules for debugging and error handling is essential for AI assistants operating under this skill, as these guidelines eliminate ambiguity in failure reports and prevent endless iterative debugging loops.

Matter-of-Fact Tone for Errors (Rule 8)

According to Rule 8 in skills/i-have-adhd/SKILL.md, error reports must suppress emotional language entirely. Phrases like "Uh oh" or "Oh no" are prohibited. Instead, the assistant must deliver a four-part report covering the file/line location, observed symptom, inferred cause, and minimal corrective step.

This approach appears in the evaluation cases where the expected output identifies a missing Authorization header without dramatic preamble.

Example from the skill documentation:

Test fails at `auth.spec.ts:42`: expected 200, got 401.
Cause: request is missing an `Authorization` header.
Fix: add `Authorization: Bearer <token>` to the request headers.

The Debug Spiral Rule (When to Break the Rules)

The second critical guideline appears in the "When to break the rules" section of SKILL.md. If three consecutive turns pass without resolving the issue, the assistant must stop applying the same category of fixes.

The protocol requires:

• Naming the likely faulty assumption explicitly
• Asking exactly one focused diagnostic question before continuing

This prevents the "debug spiral" where an assistant iteratively applies similar patches without addressing root causes.

Example interaction following this rule:

The test still fails after adding the header.
Possible wrong assumption: the token value is invalid.
**Question:** Is the token being generated correctly?

Notice the structure: the first line states the action, the assumption follows as plain prose, and the bold question isolates the single diagnostic inquiry.

Source Implementation and Validation

The repository validates these rules through concrete test cases stored in evals/cases.jsonl. These cases verify that assistants correctly identify debugging scenarios—such as diagnosing a missing Authorization header—while adhering to the matter-of-fact tone and spiral-breaking protocols.

The SKILL.md file serves as the canonical source for both Rule 8 and the debug spiral guidance, ensuring consistent behavior across all debugging sessions governed by the i-have-adhd skill.

Summary

• Error Rule 8: As defined in skills/i-have-adhd/SKILL.md, mandates plain error reports without emotional filler, listing file location, symptom, cause, and fix.
• Debug Spiral Protocol: After three unsuccessful attempts, stop repetitive fixes and ask one diagnostic question about the underlying assumption per the "When to break the rules" section.
• Validation: Rules are tested against concrete cases in evals/cases.jsonl to ensure proper implementation of the i-have-adhd rules for debugging and error handling.

Frequently Asked Questions

What emotional phrases does Rule 8 prohibit?

Rule 8 explicitly bans interjections like "Uh oh," "Oh no," and similar emotive language from error reports. The i-have-adhd skill requires instead a direct statement of the problem and solution, following the format demonstrated in SKILL.md.

How does the debug spiral rule determine when to intervene?

The trigger occurs after three consecutive turns showing the same unresolved issue. At this breakpoint, the assistant must pause, identify the potentially wrong assumption, and pose a single diagnostic question rather than attempting another similar fix.

Where are the i-have-adhd debugging rules documented?

The primary documentation resides in skills/i-have-adhd/SKILL.md, specifically in Rule 8 and the "When to break the rules" section. Concrete evaluation examples that test these protocols are stored in evals/cases.jsonl according to the ayghri/i-have-adhd source structure.

Why does the skill require exactly one diagnostic question?

This constraint prevents overwhelming the user with multiple hypotheses and forces the assistant to identify the most critical faulty assumption. It streamlines the debugging process according to the cognitive efficiency principles underlying the ayghri/i-have-adhd repository.

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