Guide · AI coding & owned software
Write a Bug Report Your AI Coding Tool Can Investigate
Give a coding assistant a reproducible failure, relevant evidence, and a clear boundary for the fix.
A coding assistant can generate a fix quickly. Whether it's fixing the right problem depends heavily on the report you give it. Start with the behavior you observed, then provide enough evidence to reproduce it. Leave room for investigation instead of prescribing a cause you haven't confirmed.
Describe a specific failure
"Fix the dashboard" doesn't identify the broken behavior. "When a member refreshes the projects page, the loading indicator remains visible even though the request returns successfully" gives the assistant a concrete place to look.
Separate the expected result from the actual result. Include the relevant role, route, input, and starting state. If the problem happens only after a particular sequence, list that sequence. The assistant should be able to tell when it has reproduced the issue and when its proposed change has corrected it.
Share evidence with context
Include the error message, the time of the attempt, and the relevant log excerpt. Explain where the evidence came from. A browser console error and a server-side error may point to different parts of the application.
Remove secrets and unnecessary customer data before sharing diagnostics. Keep enough structure to understand the failure. A redacted example that changes the shape of the input can accidentally remove the very condition that caused the bug. Use a synthetic example that reproduces the same behavior when possible.
Ask for an investigation before a rewrite
A useful instruction might be: "Reproduce the failure, identify the relevant data path, explain the likely cause, and make the smallest coherent fix. Preserve the existing permissions and unrelated behavior." That asks for a reasoned change without dictating an implementation prematurely.
The smallest coherent fix isn't always the fewest lines. A symptom in one component may come from a shared helper. What matters is whether the scope follows from the evidence and whether the change can be reviewed without guessing at unrelated edits.
Give the assistant a way to prove the result
Specify the original scenario and a nearby case that must keep working. In a hypothetical file-upload bug, the original failure might involve a permitted file at the size limit. A smaller permitted file should still work, and an oversized file should still be rejected with a useful message.
Use tests where they can verify the behavior meaningfully. For an interface issue, a successful build alone doesn't establish that the interaction is fixed. The appropriate check depends on the problem: a focused automated test, a reproduced request, or a deliberate review of the actual workflow.
Read the proposed change
Inspect the files that changed and ask how each one relates to the bug. GitHub's review guidance recommends reviewing changes file by file; that is a useful habit even when an assistant wrote the patch. Pay attention to changed dependencies, permission checks, and error handling.
If the patch removes a check to make the error disappear, ask what the check was protecting. If it introduces unrelated cleanup, separate that work from the fix. Finish with a record of the cause, the change, and how it was verified so the next investigation starts with evidence rather than a vague memory.