- Home
- Skills
- Testing & Debugging
- Debugging Agent Runs — Break Loops and Stale State
Works with the AI Agents you already use
Debugging Agent Runs — Break Loops and Stale State
A five-step recovery loop for when the agent itself is stuck: looping, drifting, out of context or trusting stale state.
Free
Debugging Agent Runs — Break Loops and Stale State
Example session with this skill installed
You've been going in circles for 20 minutes. Use debugging-agent-runs. Here's the tail of the session:
[assistant] I created app/exporters/csv_exporter.py with export_orders_csv(). Running tests.
$ pytest tests/test_exports.py
E ModuleNotFoundError: No module named 'app.exporters'
[assistant] The import path is wrong. Changing to `from exporters.csv_exporter import export_orders_csv`.
$ pytest tests/test_exports.py
E ModuleNotFoundError: No module named 'exporters'
[assistant] Switching to a relative import: `from .exporters.csv_exporter import ...`.
$ pytest tests/test_exports.py
E ImportError: attempted relative import with no known parent package
[assistant] Adding sys.path.insert(0, "app") at the top of the test file. This should now work.
$ pytest tests/test_exports.py
E ModuleNotFoundError: No module named 'app.exporters'
[assistant] Let me also add an __init__.py to tests/ and retry with a different import style...
- Read your context and instructions
- Compiled the debugging agent runs
Summary. This is a loop. The same ModuleNotFoundError has come back four times, and each attempt changed only the import wording. No attempt produced new information. The first message also says "I created app/exporters/csv_exporter.py", but nothing after it checked that the file is really on disk. Every later step rests on that assumption.
Failure mode
| Symptom in the transcript | Likely cause (from the skill's table) |
|---|---|
| Four import rewrites, the same error each time | Loop: no new information between attempts |
| "This should now work" right before it failed again | Stale state: trusting memory over the real files |
Next step is changing tests/ and the import style again | Scope creep: the edits are moving away from the failing unit |
Recovery loop
1. Objective in one sentence.
Make tests/test_exports.py import export_orders_csv from app.exporters.csv_exporter and pass, without changes to sys.path.
2. Check the real state, not memory. Run these from the repo root and paste the raw output:
git status --short
git branch --show-current
ls -la app/ app/exporters/
These have not been run here. The questions to answer: is csv_exporter.py actually in app/exporters/? Does app/exporters/__init__.py exist? Does app/__init__.py exist? Are we on the branch we think we are?
3. Shrink the scope. Leave pytest and the test file out of it. The smallest reproduction is the import alone:
python -c "import app.exporters.csv_exporter as m; print(m.__file__)"
4. One discriminating check. That one-line import, run from the repo root, decides which branch you're in:
| Result | Meaning | Next action |
|---|---|---|
ModuleNotFoundError: No module named 'app.exporters', and ls shows no app/exporters/ | The file was never written, or it is on another branch or worktree | Create it at the right path, or switch branches. No import changes needed |
Same error, app/exporters/csv_exporter.py exists, no __init__.py | Package marker missing in a project that doesn't use namespace packages | Add app/exporters/__init__.py |
| Prints a file path, but pytest still fails | Pytest's rootdir or import mode differs from plain Python | Check pyproject.toml / pytest.ini for pythonpath or rootdir |
5. Retry with a different approach. First undo the edits made while looping:
- Revert the
sys.path.insertand the relative-import changes intests/test_exports.py. - Don't add
tests/__init__.pyunless the check above points to it.
Then make the single change the check points to and run pytest tests/test_exports.py. If the error message changes, that counts as progress. If it doesn't, the plan didn't change and you are still looping.
Stop condition
If one full pass gives no progress, stop and hand it back to you. The handoff should say: the objective (step 1), the raw git status/ls output, the result of the one-line import, and which row of the table above it matched.
Next steps
- Run the three commands in step 2 and the one-liner in step 3, and paste the output. Nothing more gets edited until then.
- Revert the
sys.pathand relative-import edits. - Make the one fix the check points to. Once the import resolves and an actual assertion fails, this is a code bug and
fixing-bugstakes over.
Connects securely to your tools. The creator never sees your data.
About this skill
Debugging Agent Runs is for when the problem is the run, not the code. The agent keeps retrying small variations of the same fix, rewords the same prompt, widens its scope while nothing lands, or acts on what it remembers instead of what is actually on disk.
Problems it solves
- The same failing action retried three or more times with reworded prompts and no new information.
- Edits that land on the wrong branch or in the wrong files.
- Confident "this should work now" claims that don't match reality.
- Context overflow, so the agent forgets earlier decisions.
- Repeated 429s or timeouts.
- Scope creep while the original goal stalls.
What's inside. A table maps symptoms to likely causes: loop, context overflow, rate limit, branch/diff drift, stale state, scope creep. Then a recovery loop runs in a fixed order:
- Restate the real objective in one sentence.
- Check the actual state of the world (re-read files,
git status/diff, real command output) instead of trusting memory. - Shrink the failing scope to the smallest reproduction.
- Run one check that tells you which explanation is true.
- Only then retry, and change the approach, not just the wording.
There is a short list of anti-patterns. There is also a clear rule for when to stop: after one full pass with no progress, or when the run hits a budget or rate limit, the agent hands off to you with the objective, what it verified, the check it ran and where it is blocked.
What it is not. The skill says so itself: it is a discipline the agent follows, not a hidden runtime that repairs things automatically. For bugs in your product code, its companion fixing-bugs takes over.
When it triggers. When a run isn't converging and reworded retries aren't helping, or when you ask for it.
Free and MIT-licensed. Part of the claude-skills-czl collection.
Source on GitHub: this skill · full repository
It is a discipline the agent follows, not a runtime that automatically fixes a stuck process. It needs file and shell access to check the real state. Once the problem is isolated to a bug in product code, switch to the fixing-bugs skill.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
2 uses
Times used to date
Free forever
No account required to browse
Trust & safety
Security scan
Security scan passed 1 month ago
- Free with an Agensi account
Permissions
File Scopes
- Reads files: yes. It re-reads the files involved and the project's `learnings/` folder. - Edits files: not as part of the recovery loop, which is about diagnosis. After the discriminating check, the agent makes the one fix that check points to. It may add a `learnings/` entry for a project-specific failure mode. - Shell commands: yes, read-only checks: `git status`, `git diff`, listing files, and a single failing test or command chosen to discriminate between explanations. - Network access: none. - Git / GitHub: git is read-only (status/diff). No commits, pushes or GitHub actions.