# Debug a vibe-coded app without breaking it further

PaperChase prompt pack, version 1.0. 12 prompts for Cursor, Claude Code, Codex, Windsurf, Bolt, Lovable, Replit or any AI coding tool.

## How to use this pack

1. Commit before every debugging session: `git add -A && git commit -m "before debugging"`. No git? Download a copy of the project folder first.
2. Put your tool in ask, plan or chat mode for prompts 1 to 4. These prompts read code; they should not change it.
3. Replace everything in [square brackets]. Leave the rest as written. The rules are the point.
4. One bug per session. When the bug is fixed, commit, then start a new chat for the next one. Long chats drift.

## The debugging loop

Reproduce. Isolate. Change one thing. Verify. Commit. If a step fails twice, go to prompt 8 (Stop and revert).

## Contents

1. Reproduce before you touch anything
2. Read the error like a senior developer
3. Explain this file before you edit it
4. Find code that is never called
5. One change, then prove it
6. Check for packages that do not exist
7. Bisect the bug with git
8. Stop and revert
9. Fix an error that only happens in the production build
10. Untangle a loop of failed fixes
11. Write the test that would have caught it
12. Leave a note for future you

---

## 1. Reproduce before you touch anything

```
Do not edit any files yet.
Bug: [describe what happens] when I [steps to trigger it].
Expected: [what should happen instead].
1. List the 3 most likely causes, ranked, with the file and function you suspect for each.
2. For the top cause, give me one command, log line or browser check that would confirm or rule it out.
3. Wait for me to run it and paste the result before you propose any change.
```

Why it works: a ranked guess plus a test stops the agent from editing on its first hunch.

## 2. Read the error like a senior developer

```
Here is the full error and stack trace: [paste everything, not a summary].
Do not edit files. Tell me:
1. The single line in MY code (not a library) where this starts, with file and line number.
2. In plain words, what the program expected at that line and what it got instead.
3. Whether this is a symptom of something earlier. If so, where to look next.
Ignore any warnings that are unrelated to this error.
```

## 3. Explain this file before you edit it

```
Before we change [file path], explain it to me:
1. What it is responsible for, in two sentences.
2. Every function in it, one line each, and who calls it.
3. Any state, environment variable, database table or external API it depends on.
4. The parts you are least sure about.
Do not suggest improvements yet.
```

Use this when the agent wants to edit a file it has not read in this chat.

## 4. Find code that is never called

```
Search the project for functions, components, routes and files that nothing imports or calls.
List each one with its path and why you think it is unused.
Do not delete anything. Mark each as: safe to remove, probably unused, or unsure.
Also list any two files that look like duplicates of each other (for example utils.ts and utils2.ts).
```

AI tools often create a second version of a file instead of editing the first. The bug is frequently in the copy you are not looking at.

## 5. One change, then prove it

```
Make the smallest change that fixes the cause we confirmed.
Rules: touch at most [2] files. Do not rename, reformat or reorganize anything unrelated. Do not add new dependencies.
After the change: show the diff, tell me exactly how to verify the fix, and name one thing that could have broken because of it.
Stop and ask me before running a database migration, deleting files or changing environment variables.
```

## 6. Check for packages that do not exist

```
List every import and every package in [package.json / requirements.txt / pyproject.toml].
For each, tell me whether it is a real, published package and whether the specific function or component we import from it exists in the version we have installed.
Flag anything you are not certain about instead of assuming it exists.
Then give me the exact command to verify each flagged item myself (for example npm view [package] or pip show [package]).
```

Run the verification commands yourself. Do not trust the answer alone.

## 7. Bisect the bug with git

```
The bug was not there at commit [good commit or "last week"] and is there now.
Walk me through git bisect step by step: the exact commands, what to test at each step and how to mark good or bad.
Do not run the commands yourself. When I tell you the first bad commit, read only that diff and explain what in it causes the bug.
```

## 8. Stop and revert

```
Stop making changes. We are going in circles.
1. Summarize every change you made in this session, file by file.
2. Tell me which of those changes are still needed, if any.
3. Give me the git command to return to the last commit, and the command to keep a copy of the current state on a branch first.
Do not run any of them. I will.
```

Then start a fresh chat with prompt 1 and the summary from step 1.

## 9. Fix an error that only happens in the production build

```
This works with [dev command] but fails with [build or start command]. Full output: [paste].
Do not edit files yet. Check these common causes and tell me which apply, with evidence:
- code that runs on the server but uses browser-only objects (window, document, localStorage)
- environment variables that exist locally but not in the build environment, or are missing a required public prefix
- imports with the wrong letter case that work on my machine but not on Linux
- dynamic values used where the framework expects static ones at build time
Then propose the smallest fix for the one with the strongest evidence.
```

## 10. Untangle a loop of failed fixes

```
We have tried [number] fixes for this bug and none worked. Here is what we tried: [list or paste summary from prompt 8].
Assume our understanding of the cause is wrong.
1. List the assumptions every one of those fixes shared.
2. For each assumption, describe one check that would prove it false.
3. Rank the checks by how quickly I can run them.
Do not suggest another fix until at least one assumption is disproved.
```

## 11. Write the test that would have caught it

```
The bug was: [description]. The fix was: [summary or diff].
Write one automated test that fails on the old code and passes on the new code, using the test setup this project already has.
If the project has no tests yet, propose the lightest setup for this stack and write only this one test.
Tell me the command to run it.
```

## 12. Leave a note for future you

```
Write a short entry for a DEBUGGING.md file in the project root:
- Date: [today]
- Symptom: what I saw
- Cause: what it actually was
- Fix: the files and the change
- Lesson: one sentence on how to spot it faster next time
Keep it under 120 words. Append to the file if it exists; do not rewrite earlier entries.
```

After a few months this file tells your agent, and you, where this project tends to break.

---

## Safety rules worth adding to your tool's project rules file

```
- Ask before deleting files, running migrations, changing environment variables or installing packages.
- Never print, log or commit secrets or API keys.
- Prefer editing an existing file over creating a new file with a similar name.
- After every change, state how to verify it.
```

License: personal and commercial use. Do not resell or republish this pack.
Questions: mgmt@paperchasewebb.com