Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+22 more

    Debugging Agent Runs — Break Loops and Stale State

    1

    A five-step recovery loop for when the agent itself is stuck: looping, drifting, out of context or trusting stale state.

    Free

    Security scanned
    Debugging Agent Runs — Break Loops and Stale State

    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 transcriptLikely cause (from the skill's table)
    Four import rewrites, the same error each timeLoop: no new information between attempts
    "This should now work" right before it failed againStale state: trusting memory over the real files
    Next step is changing tests/ and the import style againScope 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:

    ResultMeaningNext 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 worktreeCreate it at the right path, or switch branches. No import changes needed
    Same error, app/exporters/csv_exporter.py exists, no __init__.pyPackage marker missing in a project that doesn't use namespace packagesAdd app/exporters/__init__.py
    Prints a file path, but pytest still failsPytest's rootdir or import mode differs from plain PythonCheck 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.insert and the relative-import changes in tests/test_exports.py.
    • Don't add tests/__init__.py unless 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

    1. Run the three commands in step 2 and the one-liner in step 3, and paste the output. Nothing more gets edited until then.
    2. Revert the sys.path and relative-import edits.
    3. Make the one fix the check points to. Once the import resolves and an actual assertion fails, this is a code bug and fixing-bugs takes 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:

    1. Restate the real objective in one sentence.
    2. Check the actual state of the world (re-read files, git status/diff, real command output) instead of trusting memory.
    3. Shrink the failing scope to the smallest reproduction.
    4. Run one check that tells you which explanation is true.
    5. 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

    How to use

    Skills on Agensi run inside your AI agent. Copy the prompt, paste it into your agent, and it connects to Agensi and installs this skill for you. If a payment is needed, your agent shows it to you first.

    Reviews

    No reviews yet

    Be one of the first to try it. Every listed skill passes our trust checks below.

    Security scanned

    Passed our 8-point scan before listing

    Fresh listing

    Recently published to Agensi

    Free forever

    No account required to browse

    Trust & safety

    Security scanned

    Verified clean 11 days ago

    • Free to download with an account

    Listed11 days ago

    What's inside

    Frequently Asked Questions