Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+21 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

    2 usesSecurity 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

    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. 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. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 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

    Terminal / Shell
    Read Files

    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.

    Listed1 month ago

    What's inside

    Frequently Asked Questions

    This skill provides a structured recovery protocol for AI agents that are stuck in repetitive loops, hallucinating file states, or suffering from context overflow, helping them regain focus on the original objective.

    It is designed as an LLM-agnostic framework that works with any agentic system capable of following multi-step reasoning protocols, such as Claude Code, AutoGPT, or custom internal agents.

    No, this is a procedural discipline for the agent to follow to fix its own execution flow; for identifying and fixing bugs within your actual application code, you should use the companion 'fixing-bugs' skill.

    The skill is available for free under the MIT license and is delivered as a configuration guide that you can integrate into your agent's system instructions or skill library.

    The skill includes a clear 'stop rule' that triggers a hand-off to the human user if no progress is made after one full recovery cycle or if budget/rate limits are reached.

    Updates are managed via the official GitHub repository, where you can find the latest version of the recovery table and anti-pattern list to keep your agent's debugging logic current.

    New in Testing & Debugging