When Does the i-have-adhd Plugin Stop Iterating After Failed Fix Attempts?

The i-have-adhd plugin stops iterating after three failed fix attempts by default—one initial attempt plus two configurable retries—before raising an error or reporting the doubtful assumption.

The ayghri/i-have-adhd repository implements a strict evaluation runner to prevent infinite debugging loops common in ADHD-related hyperfocus patterns. Understanding when the i-have-adhd plugin stops iterating after failed fix attempts helps configure automated pipelines and interpret failure states correctly. The iteration limit is enforced through both code-level constraints in the evaluation script and documented behavioral policies.

Retry Logic Implementation in scripts/run_evals.py

The core retry mechanism lives in scripts/run_evals.py, specifically within the evaluation runner invocation logic. According to the ayghri/i-have-adhd source code, the plugin uses a bounded retry loop with exponential backoff to handle transient failures.

The Attempt Loop (Lines 58-70)

Inside the evaluation runner, a for loop controls the maximum number of execution attempts. The code uses range(args.retries + 1) to calculate total iterations, meaning the default value of 2 retries produces exactly 3 total attempts:

for attempt in range(args.retries + 1):          # ← up to 3 attempts by default

    completed = subprocess.run(..., check=False, ...)
    if completed.returncode == 0:
        break
    if attempt < args.retries:
        time.sleep(min(2**attempt, 5))

This implements exponential backoff—waiting 1 second after the first failure ($2^0$) and 2 seconds after the second ($2^1$)—while capping the delay at 5 seconds. The loop exits immediately upon success (returncode == 0) or continues until exhausting the retry budget.

Configuring the Retry Limit (Lines 29-30)

The default retry count is defined when constructing the argument parser:

run.add_argument("--retries", type=int, default=2)

This configuration means the plugin attempts to fix failures up to 3 times total before terminating, unless overridden by the user.

Documented Policy vs. Code Implementation

Beyond the code implementation, the INSTALL.md file explicitly states the behavioral contract: after three consecutive failed fix attempts, the plugin must stop and identify the doubtful assumption. This aligns with the debug spiral rule documented in skills/i-have-adhd/SKILL.md, which mandates stopping after three "still broken" turns to prevent obsessive debugging cycles.

Practical Configuration Examples

To run evaluations with the default three-attempt limit:

python -m scripts.run_evals run \
  --runner my-runner \
  --condition baseline \
  --retries 2 \
  --output results.jsonl

To increase the tolerance to five total attempts (four retries):

# scripts/run_evals.py configuration

parser = argparse.ArgumentParser()
parser.add_argument("--retries", type=int, default=4)  # 4 retries → 5 attempts

Summary

• The i-have-adhd plugin defaults to 3 total attempts (initial + 2 retries) before stopping iteration on failed fixes.
• Retry logic is implemented in scripts/run_evals.py lines 58-70 using exponential backoff with a 5-second cap.
• The --retries CLI argument defaults to 2, configurable via run.add_argument at lines 29-30.
• Documentation in INSTALL.md and skills/i-have-adhd/SKILL.md reinforces the three-failure limit as a behavioral policy to prevent debug spirals.
• After exhausting attempts, the plugin either raises a runtime error or reports the doubtful assumption depending on execution context.

Frequently Asked Questions

How many total attempts does the plugin make by default?

The plugin makes three total attempts by default: one initial attempt plus two retries. This is determined by the --retries argument default value of 2 in scripts/run_evals.py line 29.

Can I change the number of retry attempts?

Yes. Pass the --retries flag with a custom integer when invoking python -m scripts.run_evals run. For example, --retries 4 allows five total attempts. You can also modify the default value in the argument parser definition at lines 29-30 of scripts/run_evals.py.

Where is the retry logic documented besides the code?

The three-attempt limit is documented in INSTALL.md under the "Exceptions" section, which states the plugin stops and names the doubtful assumption after three failed fixes. The skills/i-have-adhd/SKILL.md file also references this rule in the context of preventing debug spirals.

What happens after the maximum number of failed attempts?

After exhausting the configured retries, the loop terminates without breaking on success. The subprocess return code remains non-zero, causing the script to raise an error or, according to the behavioral policy described in INSTALL.md, report the doubtful assumption that led to the persistent failure.

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