Tutorials & How-Tos
Writing Bug Reports AI Can Action
Structured bug reports that AI coding assistants can fix autonomously. Learn the format, context, and specificity that turns bug reports into AI-actionable tickets.
Structured bug reports that AI coding assistants can fix autonomously. Learn the format, context, and specificity that turns bug reports into AI-actionable tickets.
The quality of a bug report determines whether an AI coding assistant can fix the bug autonomously or needs extensive human guidance. Well-structured bug reports give AI everything it needs: reproduction steps, expected behavior, actual behavior, and enough context to locate the relevant code. Poorly structured reports -- "the button doesn't work" -- leave the AI guessing.
Data from teams using AI-assisted bug fixing shows the gap clearly: AI fixes 67% of well-structured bug reports autonomously on the first attempt. For poorly structured reports, that number drops to 12%. The bug complexity is comparable across both groups. The difference is entirely in the report quality.
## Bug: [Concise description of what's wrong]
### Reproduction Steps
1. [Exact sequence of actions to trigger the bug]
2. [Include specific data inputs, user states, or configurations]
3. [Note any timing dependencies]
### Expected Behavior
[What should happen when following the reproduction steps]
### Actual Behavior
[What actually happens, with specific details]
### Error Output
[Stack trace, console errors, or log output]
### Environment
- OS: [operating system and version]
- Browser/Runtime: [relevant runtime environment]
- App Version: [commit hash or version number]
- Relevant Config: [any non-default configuration]
### Relevant Code
- File: [path to the file where the bug likely exists]
- Function: [function name if known]
- Related Files: [other files that may be involved]
### Additional Context
[Screenshots, videos, or additional notes]
Reproduction steps tell the AI which code path to investigate. Without them, the AI must analyze every possible path through the application, which is slow and error-prone.
Expected vs. actual behavior defines the bug precisely. "The button doesn't work" is ambiguous. "Clicking the submit button should create an order and redirect to /orders/confirmation, but instead it shows a loading spinner indefinitely" is specific enough for AI to identify the exact failure point.
Error output gives the AI a starting point for investigation. A stack trace points directly to the failing code. Console errors identify the error type. Log output reveals the application state at the time of failure.
Environment details prevent the AI from chasing platform-specific red herrings. A bug that only occurs in Safari with a specific OS version needs a different investigation approach than one that occurs everywhere.
Relevant code pointers eliminate the search phase entirely. If you know the bug is in src/components/OrderForm.tsx, telling the AI saves it from searching the entire codebase.
AI needs to know the starting state before it can follow reproduction steps:
### Bad
1. Go to the settings page
2. Change the theme
3. Save
### Good
1. Log in as a user with admin role
2. Navigate to /settings/appearance
3. Select "Dark" from the theme dropdown (currently set to "Light")
4. Click "Save Changes"
5. Observe: page shows success toast but theme doesn't change until page refresh
The good version specifies the user role, the exact navigation path, the current and target values, and the specific discrepancy observed.
If the bug requires specific data to reproduce, include it:
### Reproduction Data
- User: must have at least 2 saved addresses
- Cart: must contain items from 2 different sellers
- Payment: use a card with 3D Secure enabled
### Steps
1. Log in with a user matching the above criteria
2. Navigate to checkout
3. Select the second saved address
4. Click "Pay Now"
5. Complete 3D Secure challenge
6. Observe: order is created with the first address, not the second
Some bugs depend on timing. If the bug requires fast interaction, slow network, or specific sequencing, say so:
### Timing Note
This bug requires clicking "Submit" twice within 500ms.
It does not occur if you wait more than 1 second between clicks.
This suggests a debounce or request deduplication issue.
This timing context tells the AI exactly what kind of bug to look for -- a missing debounce or a race condition in request handling. For more on how AI handles these investigations, see our guide on debugging techniques.
"The app is slow" doesn't give AI anything to investigate. "The /dashboard page takes 8 seconds to load when the user has more than 100 items, compared to 0.5 seconds with fewer than 10 items" points directly to a query performance issue.
AI can interpret screenshots, but text descriptions are more precise and actionable. A screenshot showing an error modal is less useful than the text of the error message, the stack trace from the console, and a description of what action triggered the modal.
When a bug produces an error message, stack trace, or console output, include it. This is the single most actionable piece of information for AI debugging. Copy the full text -- don't summarize or truncate. Stack trace analysis is where AI debugging skills excel.
Bug reports written for team members who share context often omit details that AI doesn't have. "It happens on the new feature" assumes the AI knows which feature, which branch, and which code was recently changed. Be explicit about everything.
Each bug report should describe exactly one bug. When a report contains multiple issues, AI may fix one and ignore others, or confuse the symptoms of different bugs during diagnosis.
Teams with large backlogs of poorly structured bug reports can use AI to upgrade them. An AI skill can read a vague bug report and generate clarifying questions:
Original: "Search doesn't work on mobile"
AI analysis:
- What search? (main search bar, in-page search, filter search)
- What mobile? (iOS Safari, Android Chrome, responsive web, native app)
- What "doesn't work"? (no results, wrong results, crashes, UI broken)
- When did it last work? (was this a regression or always broken)
- What search terms reproduce it? (all searches or specific queries)
Suggested rewrite pending answers to these questions.
This skill-based approach systematically upgrades report quality without requiring reporters to learn the full template upfront.
Structure bug reports using issue templates that enforce the AI-actionable format:
name: Bug Report
description: Report a bug (AI-actionable format)
body:
- type: textarea
id: reproduction
attributes:
label: Reproduction Steps
description: Exact steps to reproduce the bug
placeholder: "1. Navigate to...\n2. Click...\n3. Observe..."
validations:
required: true
- type: textarea
id: expected
attributes:
label: Expected Behavior
validations:
required: true
- type: textarea
id: actual
attributes:
label: Actual Behavior
validations:
required: true
- type: textarea
id: error
attributes:
label: Error Output
description: Stack traces, console errors, log output
render: shell
Templates enforce structure. Structure enables AI automation. For guidance on GitHub integration with AI tools, see our dedicated guide.
AI can triage well-structured bug reports automatically:
Track the correlation between report quality and AI fix rate:
| Report Quality Score | AI Fix Rate (First Attempt) |
|---|---|
| Has reproduction steps | 54% |
| + Has expected/actual behavior | 61% |
| + Has error output | 67% |
| + Has file/function pointers | 73% |
| Missing all of the above | 12% |
Each additional element increases the AI fix rate. The cumulative effect is dramatic: a complete report is 6X more likely to be fixed autonomously than an incomplete one.
If a bug report takes more than 30 seconds to understand, it needs more detail. This isn't about length -- it's about clarity. A three-sentence report with specific reproduction steps is better than a two-paragraph report with vague descriptions.
Could a developer who has never seen the codebase understand this bug report well enough to start investigating? If not, the AI won't be able to either. Write for someone with zero context.
Before submitting a bug report, follow your own reproduction steps on a clean environment. If you can't reproduce it from your own instructions, the AI won't be able to either.
Yes. Even if a human will fix the bug, a well-structured report saves investigation time. The format that works for AI works even better for humans.
Document the conditions under which you've seen the bug, including approximate timing and frequency. Note that reproduction is intermittent. AI can still investigate intermittent bugs by analyzing the code for race conditions, timing dependencies, and state corruption patterns.
Include it as additional context, not as the primary description. Label it clearly: "Hypothesis: this might be caused by X." The AI will consider your hypothesis but won't be limited by it.
Detailed enough that someone (or an AI) with no context can reproduce the bug on the first attempt. When in doubt, add more detail.
Report it the same way. Note that the code was AI-generated and include the prompt or context that produced it. This helps the AI understand the original intent when fixing the bug.
Explore production-ready AI skills at aiskill.market/browse or submit your own skill to the marketplace.
Recognize patterns of context failure: lost-in-middle, poisoning, distraction, and clash
Debug Python: pdb REPL + debugpy remote (DAP).
Debug Node.js via --inspect + Chrome DevTools Protocol CLI.
4-phase root cause debugging: understand bugs before fixing.