A useful AI bug report has six parts: observed behavior, expected behavior, reproduction path, relevant context, evidence, and fix boundaries. The goal is not to write more words. It is to remove ambiguity before the model starts guessing.
The Problem With "It Doesn't Work"
"It doesn't work" is emotionally accurate and technically empty. It tells the AI that something is wrong, but not what changed, where to look, which behavior matters, or how to tell whether the fix worked.
That gap is where bad AI debugging begins. The assistant sees a symptom, invents a likely cause, edits the most obvious file, and hands back a patch that may fix one case while breaking another. It feels productive because code changed. It is not necessarily progress.
A better bug report slows the first step down. You give the model enough structure to investigate instead of improvise. You are not asking it to be less creative. You are giving it a smaller, sharper maze.
The Six Fields That Matter
- Observed behavior: what actually happens, in user-visible terms.
- Expected behavior: what should happen instead.
- Reproduction path: the shortest set of steps that triggers the bug.
- Relevant context: files, routes, components, recent changes, environment, or feature flags.
- Evidence: error text, logs, screenshots, failing test output, network response, or data sample.
- Fix boundaries: what the assistant may change and what it should leave alone.
The last field is the one people skip most often. If you do not set boundaries, AI may "fix" the bug by changing product behavior, weakening validation, removing a test, hiding an error, or adding a new abstraction around a small issue.
Boundaries make the debugging conversation reviewable. "Find the root cause before editing." "Do not change the API contract." "Prefer a one-file fix if possible." "Do not refactor unrelated code." Those are not micromanagement. They are engineering constraints.
A Copy-Paste Prompt
"Debug this issue. First restate the bug in terms of observed behavior, expected behavior, reproduction path, likely area, and missing evidence. Then propose the smallest investigation plan. Do not edit code until you have named the likely files, the main risk, and the validation step."
This prompt does two useful things. It forces the assistant to reflect the problem back before acting, and it separates investigation from implementation. If the model misunderstands the bug, you catch it before it writes code.
Good Bug Reports Are Specific, Not Long
You do not need a thesis. You need the right signals. A short report can be excellent if it names the behavior and gives a reliable reproduction path.
Weak
"The dashboard is broken after login. Please fix it."
Better
"After login, the dashboard loads but the project list is empty. Expected: show the user's projects. Repro: sign in as a user with two projects, go to /dashboard, refresh once. Network tab shows GET /api/projects returns 200 with data. The UI renders No projects yet. Please investigate the dashboard rendering path before editing. Do not change the API response shape."
The second version is not much longer, but it removes several wrong paths. The API is returning data. The bug is likely in client state, filtering, rendering, or data mapping. The assistant also knows not to "fix" it by changing the backend contract.
Give Evidence, But Curate It
More context is not always better. Dumping a full terminal scroll, entire repository tree, or every log from the last hour can bury the useful clue. AI debugging improves when evidence is selected around the failure.
- Error messages: include the first meaningful error and the stack frame that points into your code.
- Logs: include the lines immediately before and after the failure, not the whole session.
- Network responses: include status code, endpoint, and a small representative payload.
- Tests: include the failing test name, assertion, expected value, and actual value.
- Recent changes: include the files or feature area touched since the bug last worked.
When the evidence contains secrets, customer data, tokens, emails, or private business information, redact it before sending it to a cloud AI tool. Preserve the shape of the data while replacing sensitive values.
Ask for a Diagnosis Before a Patch
The first useful answer is not always code. Often it is a diagnosis: "The API returns data, but the component filters on project.ownerId while the payload now uses owner_id." That sentence is worth more than a blind patch because it gives you something to verify.
A diagnosis-first workflow also protects you from accidental fixes. If the assistant proposes to change three files before explaining the cause, ask it to stop and identify the specific mismatch, missing state update, race condition, or contract violation.
Do not accept a generated fix if you cannot state why it fixes the reproduction path. "The tests pass" is good. "The root cause makes sense and the tests pass" is better.
When You Cannot Reproduce It
Some bugs are intermittent. That does not make the report useless. It changes the goal from "fix this exact path" to "instrument and narrow the suspect area."
For intermittent bugs, give the assistant frequency, affected users, known non-affected cases, timestamps, environment, and any recent deploys. Then ask for logging, guardrails, or a hypothesis list before asking for a fix.
"This bug is not reliably reproducible. Before proposing a fix, list the top three plausible causes, what evidence would distinguish them, and the smallest logging or test change that would make the next occurrence easier to diagnose."
Use Boundaries to Prevent Overfixing
AI tools like to be helpful. In debugging, that can mean widening the change until the original bug is hidden inside a refactor. Overfixing makes review harder because you no longer know which edit mattered.
Good boundaries keep the fix proportional. Tell the assistant whether it may add a test, change copy, alter a schema, modify API contracts, introduce dependencies, or touch shared utilities. If the bug needs a larger change, the model can say so and explain why.
Useful Boundaries
- "Do not change public API behavior without calling it out first."
- "Keep this to the checkout flow unless the root cause is clearly shared."
- "Add a failing test before changing implementation if you can reproduce it locally."
- "Avoid refactors unless they are necessary for the fix."
- "If the safest fix needs a migration, stop and explain the migration plan first."
The Bug Report Becomes the Acceptance Test
A good bug report is not just an input to AI. It is the checklist you use after the patch arrives. Can you follow the reproduction path and see the expected behavior? Did the fix stay inside the boundaries? Did it add or update a test near the failure? Did it avoid unrelated cleanup?
That is the quiet advantage of writing the bug clearly. It gives the assistant a better task, and it gives you a better standard for saying yes.
Pair this with Debugging with AI, The AI Plan Before Code, Why Small Diffs Win With AI, and AI Code Review.