When an AI-built page breaks, repeatedly asking 'fix it' can produce a growing pile of unrelated changes. A better debugging loop starts with something you can observe: the exact action, expected result, actual result and environment. This guide follows a signup button that stops working after a change. You do not need to recognize every line of code to gather a useful report and inspect whether a repair helped.
What you will leave with
A reproducible bug report, a focused repair, evidence that the original problem is fixed, and a preserved recovery point.
Step 1
Protect the last working state
Before another repair attempt, inspect the current changes and record the last known working commit or deployment. Preserve uncommitted work that belongs to you or another collaborator. If real users are affected, consider restoring a known working deployment while investigating separately. Do not reset the repository or delete files just to make an error disappear. Recovery and diagnosis are related jobs, but they need not happen in the same live environment.
You can identify a recovery point and know which current work must be preserved.
Step 2
Describe the failure so someone else can repeat it
Write the smallest sequence that triggers the problem: open this URL, fill these sample values, press this button. State what you expected and what happened instead. Include whether you were signed in, which browser you used and whether the issue occurs locally or on a particular deployment. Prefer a real error message or screenshot over a vague judgment. Remove secrets and personal information before sharing diagnostic material.
Try this instruction
Reproduce this bug before editing: [steps]. Expected: [result]. Actual: [result]. Environment and revision: [details]. Inspect the relevant code and logs, identify the likely cause and make the smallest justified repair. Preserve unrelated work. Verify the original steps afterward and report what remains untested.
The agent or another person can reproduce the same failure from your instructions.
Step 3
Find the layer that failed
A build error prevents the app from being assembled; a browser error happens while someone uses it; a server error happens behind the request; a data-policy error may reject an otherwise valid action. Ask the agent which evidence supports its diagnosis. On Vercel, inspect the exact failed deployment's build log rather than an older run. A final 'command failed' line is a summary, so look for the more specific error above it.
The diagnosis identifies an observed failure and the component responsible, not only a guess based on the symptom.
Step 4
Change one cause and inspect the diff
If the button points to the wrong destination, repair that destination instead of rewriting the page. If configuration is missing, correct the relevant environment rather than hardcoding a secret. Ask for an explanation of each changed file and why it is needed. A focused diff makes review and reversal easier. When a larger change is genuinely necessary, preserve the original bug report and explain the dependency that makes the expansion unavoidable.
Every changed file has a reason connected to the observed failure.
Step 5
Run the check that would have caught the problem
Repeat the original steps with the same sample input. Then try a nearby case: an empty field, a wrong value, a signed-out session or a second submission, depending on the feature. Run the project's relevant existing tests and production build. Add a regression test when the behavior is important and the test can catch this failure again. Avoid a test that merely repeats the implementation without checking an actual expected result.
The original reproduction passes, relevant nearby behavior still works and failed checks are visible.
Step 6
Verify the repair in the environment that was broken
A local fix does not prove the deployed app works. Deploy through the normal preview process, inspect its actual URL and compare configuration where needed. After the approved release, repeat the main action on production. Save the code revision and deployment evidence. If the symptom remains, return to the reproduction and new logs; do not keep stacking speculative fixes or claim success because the agent sounds confident.
The failing action works on the intended deployment, not only in the development server.
Step 7
Keep a short repair note
Record the symptom, cause, changed files, checks and remaining limits. If you must undo a committed change, a Git revert can record a new commit that reverses it, preserving history; inspect the working tree and implications before using it. Distinguish code recovery from database recovery. Save a recurring failure as a troubleshooting recipe so the next attempt starts with evidence instead of repeating the same conversation.
The handoff explains why the repair worked and how to recognize the failure if it returns.
When you get stuck
Each repair introduces unrelated problems
Return to the last clear checkpoint, reproduce one failure and require a focused explanation of the proposed diff.
The agent cannot reproduce it
Supply the exact URL, sample input, account state and error. Investigate the environment difference before changing code.
A test is green but the page still fails
Check whether the test covers the real user action and whether the deployed revision matches the code tested.
Terms explained
- Reproduction
- A repeatable sequence that demonstrates a specific failure.
- Diff
- The changes between two versions of the project.
- Regression
- Behavior that used to work and broke after a change.
Sources and further reading
The workflow and templates are teaching guidance. The sources below support the underlying tools and concepts; product setup and availability can change.
Take it into your next task
Your completion checklist
0 / 7 checked
Checks are saved on this browser. Mark them only after you inspect the evidence. These are your checks, not an automated certification.