“The app is broken. Fix it.” tells an AI coding tool how you feel, but not what failed. The tool may patch the first suspicious file and miss the real cause.
A good bug report is a short recipe. It shows where the problem appears, how to repeat it, what should happen, and what happened instead.
What facts does the AI need?
Start with facts you can observe. You do not need to guess which code is wrong.
| Fact | Question | Example |
|---|---|---|
| Location | Where does it happen? | Published checkout page on a phone |
| Starting state | What was true before the action? | One item is in the cart |
| Steps | What did you do? | Open cart, select Checkout, enter email |
| Actual result | What happened? | The page becomes blank |
| Expected result | What should happen? | The payment page opens |
| Timing | When did it last work? | It worked before today’s coupon change |
| Evidence | What can the AI inspect? | Screenshot and exact error message |
Lovable’s official debugging guide recommends describing what broke, where it broke, what you expected, and what happened instead. It also recommends attaching a screenshot or exact error when available. Read Lovable’s debugging guide.
How do you write steps that another person can repeat?
Begin from a known state. Then write one action per line. Include the device or account type only when it changes the result.
Where
The published checkout page on an iPhone-sized screen.
Starting state
A signed-out visitor has one item in the cart.
Steps to repeat
1. Open the cart.
2. Select Checkout.
3. Enter a valid email address.
4. Select Continue.
Actual result
The page becomes blank. No payment page opens.
Expected result
The payment page should open for the same cart total.
Last known working state
This worked before the coupon feature was added today.Run the steps twice before sending them. If the bug only happens sometimes, say that. Do not change the report to make it sound certain.
What evidence should you attach?
A screenshot helps with layout and visible error states. A short screen recording helps when timing or several clicks matter. An exact error message gives the AI a phrase it can search in the project and logs.
- Capture the whole broken area, not only one pixel.
- Paste the exact error instead of rewriting it from memory.
- Say whether the problem appears in preview, at the public address, or both.
- Include the last change that may be related.
- Remove customer names, email addresses, private links, and access keys.
Never paste a secret API key or a real customer’s private data into a prompt. If an error includes either one, replace that part with a clear label such as [private key removed].
How do you ask for the cause before another patch?
If one quick fix already failed, stop asking the AI to “try again.” Ask it to investigate without changing code.
Investigate this bug before changing anything.
[Paste the location, steps, actual result, expected result, timing, and safe evidence.]
Report:
1. Whether you can repeat the bug.
2. The most likely root cause and the evidence for it.
3. Which recent change may be connected.
4. The smallest safe fix.
5. Which nearby behavior could be affected.
6. How you will prove the fix works.
Do not edit files, change data, install packages, or deploy yet. If the evidence is not enough, ask for the missing fact instead of guessing.A symptom is what you see. The root cause is the condition that creates it. Hiding an error message may remove the symptom while leaving the failed checkout in place.
What should the repair request say?
Apply the smallest fix for the confirmed root cause.
Keep cart totals, existing payment settings, login, and unrelated pages unchanged. Do not hide or ignore the error.
First create or run a check that repeats the original failure. Then make the fix and run the same check again. Also test checkout without a coupon.
Report:
- changed files
- the cause
- evidence that the original steps now pass
- evidence that normal checkout still passes
- anything you could not verify
Stop and ask before changing payment configuration or real customer data.GitHub recommends giving a coding agent a clear problem and acceptance criteria. Anthropic also recommends fixing the root cause and giving the agent a check it can run. See GitHub’s guidance and Anthropic’s best practices.
How do you stop a repeated debugging loop?
Several failed patches can make the project harder to understand. Use this reset after one or two blind attempts:
- Stop new changes.
- Ask for a list of every attempted fix and its result.
- Return to the last working checkpoint when possible.
- Start a clean conversation with the bug recipe and failed attempts.
- Ask for analysis before another edit.
We have tried two fixes and the bug remains. Stop editing. Summarize the original symptom, every attempted fix, what each attempt changed, and what evidence shows it failed. Recommend the safest working point to restore. Do not make another change.How do you confirm that the bug is really fixed?
Repeat the exact steps from your report. Then check one nearby path that should still work.
- The original steps now produce the expected result.
- The same problem does not appear after a refresh.
- The normal path without the special condition still works.
- The AI shows test, build, log, or screenshot evidence.
- You run the customer journey once yourself.
If the bug affects payment, login, or private customer data, do not treat an AI message as final approval. Keep the affected feature away from real customers until a careful test or developer review is complete.
What should you read next?
- Make the AI prove that its repair works.
- Find why an app works in preview but breaks online.
- Use a complete instruction template for the next change.
When the repaired app is ready for customers, use JustDeploy to publish and operate it.