# Skill: Diagnose and fix a stuck AI agent without panic or wasted tokens

> When an AI agent loops, argues, or talks nonsense, apply a 4-step structured diagnosis before retrying or rewriting anything. Applies whenever an agent stalls, repeats itself, produces wrong results, or behaves differently inside an app than in a direct chat.

Source: sodigi·learn — vibecoding/agent-zatupil · https://sodigi.io/learn/vibecoding/agent-zatupil

## When to use
- The agent keeps repeating the same action or command (stuck in a loop).
- The agent's answers drift, details get muddled, or it edits code that is not the problem.
- A tool you verified working in a playground behaves incorrectly inside your app.
- You are about to rephrase the same prompt for a third time hoping it will "just work."

## Core rules
- Always diagnose before treating; never repeat the same prompt 3+ times with minor wording changes.
- Check the real world (files, branch, running services) instead of trusting the agent's memory.
- The best fix is the smallest action that proves the cause, not a full rewrite.
- Categorize the failure type first: logic, state, environment, or missing rule.
- After fixing, write a short incident report (what broke, cause, fix, how you confirmed it improved).
- When the model works in a playground but fails in your app, suspect the harness (wrapper), not the model.
- Memory contamination (old topics bleeding into new sessions) and duplicate instructions clogging context are harness problems, not model problems.

## Procedure
1. Snapshot the failure in words: what was the agent trying to do, what error appeared (exact text), what was the last step that worked, what keeps repeating.
2. Make the agent describe its own state out loud (folder, branch, which files it believes exist). This alone resolves roughly half of issues.
3. Map the symptom to a cause type using the table: loop/no-exit, cluttered context, crashed tool/service, lost goal, broken wrapper.
4. Apply the smallest targeted fix: restate the goal in one sentence, or clear context to only the goal and blocker, or check what is actually on disk, or narrow the task to one file/command/test.
5. If the issue persists only inside your app, audit the harness layers: system prompt, history, memory, tool selection, tool execution, output rendering. Ask: can the agent skip a required tool? Does old content surface in new sessions?
6. Write a short report: what broke, cause, action taken, how you verified improvement.

## Ready-to-use prompt
```
Stop. Do not rewrite code from scratch. Run a step-by-step diagnosis first.

1. In plain words, describe exactly what you were trying to do and what error appeared.
2. Name the last step that definitely worked.
3. Check reality, not your memory: is the server running, what folder am I in, what branch, which files actually exist on disk.
4. Match the symptom to a cause type: logic (wrong reasoning), state (world is not what you think), environment (external service not running), or missing rule (instruction was never given). Name the single most likely cause.
5. Propose the smallest action that would confirm that cause. Do only that. Do not touch other code.
6. End with a short report: what broke, the cause, what you did, how to tell it got better.
```

## Pitfalls
- Repeating the same prompt with slightly different words -- this is the top anti-pattern; diagnosis must come first.
- Trusting the agent's memory about file or service state instead of actually checking disk/branch/process.
- Nuking and rewriting the whole project because a small root cause was never identified.
- Blaming the model when the real problem is the harness (wrapper) around it.
- Celebrating "fixed" without writing the incident report, guaranteeing the same issue recurs.
- Asking for "reset your state" -- agents cannot do this; address the actual cause instead.