How the i-have-adhd Skill Handles Debug Spirals and Determines When to Stop Iteration

The i-have-adhd skill immediately halts automated code iteration upon detecting three consecutive failed debugging attempts, forcing a pivot to root-cause analysis by naming a potentially incorrect assumption and asking a single diagnostic question.

The ayghri/i-have-adhd repository defines an LLM persona designed to optimize development workflows and prevent common failure modes in AI-assisted coding. Within this skill definition, a specific safeguard exists to handle debug spirals—recursive loops where repeated code changes fail to resolve the underlying issue. The mechanism is explicitly codified in the skill’s source to stop wasteful iteration and force higher-level problem solving.

What Is a Debug Spiral?

In the context of this skill, a debug spiral occurs when the assistant produces three successive coding attempts that are each met with feedback indicating the problem persists or is "still broken." Rather than allowing the assistant to continue generating speculative patches indefinitely, the skill mandates an immediate intervention to break the cycle of trial-and-error debugging.

The Stop Condition in SKILL.md

The specific iteration limit is defined in [skills/i-have-adhd/SKILL.md](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md#L124-L128). Lines 124-128 under the "When to break the rules" section establish that after three consecutive failures, the assistant must stop editing code and initiate a structured diagnostic protocol instead of proceeding with a fourth modification attempt.

The rule explicitly requires:

• Detection: Recognition of three "still broken" messages in sequence
• Cessation: Immediate stop to all automated code generation
• Pivot: Transition to assumption-testing mode

Breaking the Spiral: The Override Protocol

When the stop condition triggers, the skill enforces a two-step override procedure to force cognitive reappraisal:

1. Name the underlying assumption that may be incorrect (e.g., "I assume the API endpoint is publicly accessible")
2. Ask a single diagnostic question to test that assumption (e.g., "Does this endpoint require VPN access or specific headers?")

This protocol prevents the assistant from continuing to modify code based on potentially false premises.

Implementation Example

The following pseudocode illustrates the logic applied by the skill harness when the threshold is reached:

if (consecutiveBrokenTurns >= 3) {
  // Apply the debug‑spiral override as defined in SKILL.md#L124-L128
  assistant.say(
    "I suspect the assumption that [X] is true may be wrong. " +
    "Can you confirm whether [Y] holds?"
  );
  // Stop further automated code changes
}

Why This Prevents Endless Iteration

By hardcoding the stop threshold at three attempts, the i-have-adhd skill prevents the common LLM failure mode of speculative patching—where the model generates increasingly complex workarounds without understanding the root cause. The forced pause requires the assistant to articulate its assumptions and seek validation, effectively converting an endless debug loop into a targeted troubleshooting session.

Summary

• A debug spiral is formally defined as three consecutive "still broken" feedback loops in the conversation history.
• The stop condition is triggered automatically after the third failure, as implemented at [lines 124-128 of SKILL.md](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md#L124-L128).
• Upon stopping, the assistant must name a suspect assumption and ask one diagnostic question rather than proposing new code.
• This rule exists in the "When to break the rules" section of the skill definition to prevent trial-and-error waste.
• The override forces a shift from code modification to root-cause verification.

Frequently Asked Questions

What exactly triggers a debug spiral in the i-have-adhd skill?

A debug spiral triggers when the assistant receives user feedback indicating the code is "still broken" for three consecutive turns following code modifications. This pattern signals that continued editing is likely to be unproductive.

What should the assistant do once it detects a debug spiral?

The assistant must immediately cease proposing code changes. According to the skill definition, it should instead identify one underlying assumption that might be false and ask a single, specific question designed to test the validity of that assumption.

Where is the debug spiral rule documented in the source code?

The rule is documented in [skills/i-have-adhd/SKILL.md](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md#L124-L128) within the "When to break the rules" section, specifically at lines 124 through 128.

Can the threshold for stopping iteration be configured?

Based on the current implementation in SKILL.md, the threshold of three consecutive failures is hardcoded. The skill definition does not expose a configuration parameter to adjust this count; it is enforced as a fixed safeguard against recursive debugging.

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