How i-have-adhd Detects Debugging Spirals and Decides When to Stop Iterating

The i-have-adhd skill prevents endless debugging loops by stopping iteration after three consecutive "still broken" results, then shifting to a diagnostic question that identifies the root assumption error.

The ayghri/i-have-adhd repository contains a specialized agent skill designed to reduce cognitive load during iterative debugging tasks. Unlike standard agent workflows that may loop indefinitely on failing code, this implementation defines explicit debug spiral detection logic that forces a pivot from code modification to targeted inquiry.

How Debug Spiral Detection Works

The detection mechanism operates on outcome tracking across conversation turns. When an agent attempts to fix code, it evaluates whether each intervention resolves the issue or maintains the failure state.

The Three-Turn Threshold Rule

According to skills/i-have-adhd/SKILL.md, the system defines a debug spiral as three consecutive turns producing identical "still broken" results. This threshold serves as the trigger point where normal iteration rules are suspended.

The logic implementation requires the agent to:

• Track turn outcomes: Maintain state awareness of whether each code change resolved the issue
• Detect repetition: Identify when the failure mode persists unchanged across multiple attempts
• Force intervention: Execute the "When to break the rules" clause once the threshold is reached

This three-turn limit prevents wasted computational effort and reduces frustration for users managing attention constraints.

Breaking the Loop: The Diagnostic Protocol

Once the spiral is detected, the agent abandons further code modification attempts and executes a structured diagnostic protocol defined in the skill configuration.

Stop Further Iteration

The primary directive is immediate cessation of iterative fixes. As specified in the source rules, the agent must not attempt additional code changes until the diagnostic question is answered. This hard stop prevents compounding errors from guess-based solutions.

Name the Faulty Assumption

The agent is required to articulate the likely incorrect assumption underlying the repeated failures. For example, it might state: "Assumption: The request may be missing an Authorization header." This explicit naming helps externalize the debugging logic and makes the cognitive process transparent.

Ask a Single Diagnostic Question

Rather than requesting general investigation, the agent poses one specific question designed to validate or invalidate the named assumption. The question targets the precise missing information piece, such as: "Is the token being attached correctly before the request is sent?"

Source Code Implementation

The debug spiral logic is distributed across specific configuration files within the repository structure.

SKILL.md: The Rule Definition

The authoritative logic resides in skills/i-have-adhd/SKILL.md under the "When to break the rules" section. This file contains the canonical definition of the three-turn threshold and the diagnostic protocol sequence. The skill directs the runtime to monitor turn outcomes and trigger the spiral clause when consecutive failures match.

Agent-Specific References

The rule is referenced in skills/i-have-adhd/agents/gemini.toml, which configures how the Gemini agent integration specifically handles the debug spiral clause. This demonstrates the rule's implementation across different model backends while maintaining consistent spiral detection behavior.

General Workflow Context

The AGENTS.md file at the repository root provides broader context for how debugging workflows are structured, explaining where the spiral detection fits within the general agent lifecycle and how it prevents the "fix-and-hope" anti-pattern common in autonomous coding agents.

Practical Examples of Spiral Handling

Normal Iteration Without Spiral

When fixes succeed or failure modes change between turns, the agent proceeds normally:

Step 1: Open `src/auth.ts` and add the missing Authorization header.
Step 2: Run `npm test`.
Step 3: All tests pass – done.

Triggering the Debug Spiral

When identical failures persist across three turns, the spiral protocol activates:

Turn 1: "still broken" – test fails with 401 error.
Turn 2: "still broken" – same 401 error persists.
Turn 3: "still broken" – three consecutive identical failures → debug spiral triggered.

Agent response:
**Assumption:** The request may be missing an Authorization header.
**Question:** "Is the token being attached correctly before the request is sent?"

Post-Diagnostic Resumption

After receiving user input, the agent resumes with targeted precision:

User: "Yes, the token is attached, but the header name is misspelled."
Agent: "Fix the header name to `Authorization` and rerun the test."

Summary

• Three-turn rule: The i-have-adhd skill detects debug spirals after three consecutive identical failures.
• Hard stop: Iteration halts immediately upon spiral detection to prevent endless looping.
• Diagnostic pivot: The agent names the faulty assumption and asks one specific question rather than guessing.
• Source authority: Logic is defined in skills/i-have-adhd/SKILL.md and referenced in agent-specific configuration files.
• ADHD optimization: This pattern reduces cognitive load by preventing frustrating loops and enforcing structured debugging.

Frequently Asked Questions

How does the i-have-adhd skill define a debug spiral?

A debug spiral is defined as three consecutive turns where the agent attempts code fixes but the outcome remains identically "still broken." This pattern is detected by tracking failure consistency across turns, as implemented in skills/i-have-adhd/SKILL.md.

What happens when a debug spiral is detected?

The agent immediately stops iterating on code changes and enters a diagnostic mode. It names the most likely faulty assumption (such as missing headers or incorrect variable names) and asks the user a single, targeted question to identify the missing information needed to resolve the underlying issue.

Where is the debug spiral logic implemented in the repository?

The primary logic is located in skills/i-have-adhd/SKILL.md under the "When to break the rules" section. Additional references to this behavior appear in skills/i-have-adhd/agents/gemini.toml for specific model integrations, with general workflow context provided in AGENTS.md.

Why does the skill use a three-turn threshold specifically?

The three-turn threshold balances giving the agent sufficient opportunity to attempt standard fixes while preventing the cognitive overhead and frustration of endless debugging loops. This constraint is optimized for users with ADHD by forcing a structured pivot before frustration or distraction compounds.

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