What Happens When i‑have‑adhd Encounters a Debug Spiral: Detection and Recovery Workflow

When the i‑have‑adhd skill detects a debug spiral, it interrupts the normal response flow to name the most likely false assumption and ask exactly one diagnostic question, then resumes standard formatting once the assumption is clarified.

The open-source repository ayghri/i-have-adhd implements a set of ADHD‑friendly response rules designed to prevent cognitive overload during technical troubleshooting. One critical safeguard is the debug spiral handler defined in the canonical rule set, which activates when the assistant detects a loop of endless clarification or circular reasoning that buries the actionable answer.

How the Debug Spiral Rule Is Defined in the Source Code

The rule governing debug spiral behavior is codified in two locations within the repository.

According to the canonical [SKILL.md] located at skills/i-have-adhd/SKILL.md, the skill maintains a strict 10‑rule output style that prioritizes concise, actionable guidance. The runtime‑specific implementation in skills/i-have-adhd/agents/gemini.toml explicitly defines the spiral intervention at line 21:

“…you are in a debug spiral (name the assumption that might be wrong, ask one diagnostic question)”

This directive instructs the model to suspend its standard verbose preamble and switch to a debug‑spiral mode until the conversation loop is broken.

The Four-Step Debug Spiral Workflow

When the assistant identifies a debug spiral, it executes a structured recovery protocol defined in the gemini.toml configuration:

1. Identify the risky assumption – The assistant surfaces the most likely premise that could be false (e.g., “I’m assuming the token is still valid”).
2. Ask a single, focused diagnostic question – The next turn asks the user only one clarifying question to test that assumption (e.g., “Is the token you’re using still the one issued yesterday?”).
3. Pause the normal rule set – While in this mode, the assistant temporarily suspends the usual 10‑rule output style, allowing a concise back‑and‑forth aimed at breaking the spiral.
4. Resume normal behavior – Once the assumption is confirmed or corrected, the assistant returns to the standard response flow (lead with the next action, number steps, etc.).

This workflow prevents the model from burying the answer under redundant explanations, which is particularly critical for users who require high‑signal, low‑noise interactions.

Practical Example of Debug Spiral Detection

You can invoke the skill programmatically using the OpenCode SDK. The TypeScript wrapper at extensions/i-have-adhd.ts wires this logic into various runtimes (Claude, Codex, etc.).

# Example: calling the skill from a Python script using the OpenCode SDK

from opencode import OpenCodeClient

client = OpenCodeClient()
response = client.run(
    plugin="i-have-adhd",
    command="/i-have-adhd",
    arguments={"prompt": "I'm stuck on why my API keeps returning 401."}
)

print(response.text)

Typical debug‑spiral interaction:

User: My API keeps returning 401 even though I think the credentials are correct.
Assistant (debug‑spiral mode):
> I’m assuming the request includes the correct Authorization header. 
> Is the Authorization header being sent with the request?

After the user answers, the assistant exits debug‑spiral mode and resumes its regular 10‑rule format, providing a concrete next action rather than spiraling into further speculation.

Key Files Controlling Debug Spiral Behavior

The following source files govern how i-have-adhd detects and recovers from debug spirals:

• skills/i-have-adhd/SKILL.md – Contains the canonical definition of the 10 ADHD‑friendly rules, including the debug‑spiral contingency.
• skills/i-have-adhd/agents/gemini.toml – Houses the runtime rule set with the specific debug‑spiral clause at line 21 that triggers the assumption‑naming protocol.
• extensions/i-have-adhd.ts – The TypeScript wrapper that integrates the skill into Claude, Codex, and other runtimes, handling the mode transitions between standard output and debug‑spiral recovery.
• AGENTS.md – Developer guide for locating entry points and debugging the integration logic.

Summary

• The debug spiral is a conversational trap where the assistant loops through endless clarifications without delivering actionable guidance.
• When detected, i-have-adhd triggers a specific rule from gemini.toml line 21 that mandates naming the risky assumption and asking exactly one diagnostic question.
• The skill temporarily suspends its standard 10‑rule output style during the intervention, then automatically resumes normal concise formatting after the assumption is verified.
• The logic is implemented across SKILL.md, gemini.toml, and extensions/i-have-adhd.ts, ensuring consistent behavior across Claude, Codex, and OpenCode SDK integrations.

Frequently Asked Questions

How does i‑have‑adhd detect a debug spiral versus normal troubleshooting?

The skill recognizes a debug spiral by monitoring for repetitive cycles of “thinking” or redundant clarifications that fail to advance toward a concrete solution. Unlike normal iterative debugging, a spiral lacks forward progress; once the assistant detects this stagnation, it invokes the protocol defined in skills/i-have-adhd/agents/gemini.toml to force a targeted assumption check.

What happens to the 10‑rule output format during a debug spiral?

The assistant pauses the standard 10‑rule style while in debug‑spiral mode. This suspension allows for a concise, single‑question exchange that breaks the loop without the cognitive overhead of numbered steps or action‑leading preambles. Normal formatting automatically resumes once the diagnostic question is answered and the assumption is resolved.

Can developers customize the debug spiral detection logic?

Yes. Developers can modify the rule weightings and trigger conditions by editing skills/i-have-adhd/agents/gemini.toml or adjusting the TypeScript wrapper in extensions/i-have-adhd.ts. The AGENTS.md file provides guidance on how to locate these entry points and alter the threshold for what constitutes a spiral in specific runtime environments.

Is the debug spiral handler available in all integrations of the skill?

The handler is available in any runtime that consumes the canonical SKILL.md and the agent configurations from skills/i-have-adhd/agents/. The extensions/i-have-adhd.ts file specifically wires this logic into the Claude plugin and Codex integrations, ensuring consistent spiral detection across supported platforms.

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