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

> Learn when the i-have-adhd plugin stops iterating after failed fixes. Understand its default behavior of three attempts before raising an error.

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

---

**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`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py)

The core retry mechanism lives in [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/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:

```python
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:

```python
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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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:

```bash
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):

```python

# 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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/INSTALL.md) and [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py).

### Where is the retry logic documented besides the code?

The three-attempt limit is documented in [`INSTALL.md`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/INSTALL.md), report the doubtful assumption that led to the persistent failure.