# How i-have-adhd Detects and Breaks a Debug Spiral

> Discover how i-have-adhd breaks a debug spiral by detecting stalled progress, halting changes, and asking a single diagnostic question to solve issues fast.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: how-to-guide
- Published: 2026-08-21

---

**The i-have-adhd skill breaks a debug spiral by detecting three consecutive "still broken" responses, halting code changes, and asking one focused diagnostic question to identify the faulty assumption.**

The `ayghri/i-have-adhd` repository is an open-source AI assistant skill designed with ADHD-friendly principles to prevent unproductive cognitive loops. When developers get stuck in repetitive debugging cycles, the skill implements a specific **debug spiral** detection mechanism to redirect the conversation toward resolution. This behavior is codified in the project's rule set to ensure the assistant recognizes when iterative fixes are failing and intervenes appropriately.

## What is a Debug Spiral?

A debug spiral occurs when an AI assistant repeatedly attempts code fixes without success, creating an endless back-and-forth that wastes developer time and cognitive resources. In the context of `i-have-adhd`, this pattern is specifically defined as three consecutive turns where the assistant responds with variations of "still broken" while attempting to solve the same issue.

The skill treats this pattern as a signal to stop writing code and start diagnosing root causes. Rather than continuing to generate ineffective solutions, the system pivots to hypothesis testing.

## The Three-Turn Detection Logic

The detection algorithm monitors conversation history for a specific failure pattern. According to [[`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md), rule 3 in the "When to break the rules" section states:

> "Debug spiral. If the last three turns have been 'still broken,' stop iterating on code. Name the assumption that might be wrong. Ask one diagnostic question."

This rule is located at **lines 123-124** of the skill definition file. The implementation checks the last three turns of the conversation history to determine if all contain indicators of continued failure.

## Implementation Details

### Rule Definition in SKILL.md

The core logic resides in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md), where the debug spiral rule is explicitly defined as a breaking condition. When triggered, the skill overrides its standard debugging behavior to prevent further code iteration.

The rule mandates three specific actions upon detection:

- **Stop** generating new code fixes
- **Identify** the most likely faulty assumption underlying the failure
- **Ask** exactly one concrete diagnostic question to verify that assumption

### Runtime Detection in extensions/i-have-adhd.ts

The runtime implementation in [[`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts)](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) processes the conversation history to detect spiral conditions. The system evaluates each turn to count consecutive "still broken" states, triggering the intervention protocol when the threshold is reached.

## Breaking the Spiral: The Single-Question Protocol

Once a debug spiral is detected, the skill executes a structured intervention. Instead of proposing another fix, the assistant names the probable root cause assumption—for example, "the API key is correctly set" or "the environment variable is accessible"—and poses a single verification question to the user.

This approach respects ADHD-friendly design by eliminating repetitive, unproductive loops and replacing them with targeted investigative action. The conversation pauses until the user responds, ensuring that further coding efforts are based on validated assumptions rather than guesses.

## Code Example

Below is a TypeScript implementation demonstrating how the debug spiral detection logic operates within the assistant flow:

```typescript
// Pseudo-implementation of the debug-spiral guard
function maybeBreakDebugSpiral(history: Turn[]): Turn | null {
  const recent = history.slice(-3);
  const allBroken = recent.every(t => /still broken/i.test(t.assistant));
  if (!allBroken) return null;

  // Example assumption that could be wrong
  const assumption = "the API key is correctly set";

  // Return a single-question turn
  return {
    role: "assistant",
    content: `It looks like we're in a debug spiral. The most likely issue is that ${assumption}. Can you confirm this?`,
  };
}

```

This function checks the last three conversation turns for the failure pattern, then returns a diagnostic question targeting the most probable configuration error rather than continuing with code modifications.

## Summary

- **Debug spiral detection** occurs when three consecutive turns indicate the code remains broken after attempted fixes.
- **Intervention rule** is defined at lines 123-124 of [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) under the "When to break the rules" section.
- **Implementation** spans the skill definition file and the runtime processor in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts).
- **Resolution protocol** requires naming the likely faulty assumption and asking exactly one diagnostic question to verify it.
- **ADHD-friendly design** prevents cognitive exhaustion by stopping unproductive loops and refocusing on root cause analysis.

## Frequently Asked Questions

### What triggers the debug spiral detection in i-have-adhd?

The debug spiral detection triggers when the last three turns of a conversation all contain indications that the code is "still broken." The system monitors conversation history for this specific repetition pattern, as defined in rule 3 of the skill's exception handling rules in [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md).

### Where is the debug spiral rule defined in the repository?

The rule is explicitly 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 123-124 within the "When to break the rules" section. The runtime implementation that executes this logic is located in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts).

### How does asking one question help break the debug spiral?

Asking one targeted diagnostic question forces a pause in the iterative fixing loop and shifts focus to hypothesis verification. By naming the likely faulty assumption—such as an environment variable or configuration setting—and requesting confirmation, the assistant avoids generating additional ineffective code patches based on unverified premises.

### Can the debug spiral detection threshold be customized?

The current implementation uses a fixed threshold of three consecutive "still broken" turns as specified in the [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) rule. Developers wishing to adjust this sensitivity would need to modify both the rule definition in the skill file and the detection logic in the TypeScript runtime implementation.