AI Bug Fix Workflow: A Practical Guide from Reproduction to PR

Introduction

Bug fixing is one of the most frequent tasks in software development. Yet each bug requires a full cycle of "reproduce, identify root cause, fix, test, review" -- taking more time than expected.

With DevLoop Runner, you submit a bug fix Issue and AI analyzes the cause, implements the fix, and creates a PR complete with regression tests.

This article covers how to write effective bug fix Issues, how to choose execution modes, category-specific approaches for different bug types, and how to handle critical production bugs.

Writing Bug Fix Issues

The most important factor in successful bug fixing is how you write the Issue. AI needs clear information to accurately understand the bug and implement the right fix.

Essential Elements

A good bug fix Issue includes these elements:

## Bug Summary
[What's happening vs. what should happen]

## Reproduction Steps
1. [Specific step 1]
2. [Specific step 2]
3. [Specific step 3]

## Expected Behavior
[What should happen]

## Actual Behavior
[What currently happens]

## Target Files (if known)
- [file path]

## Environment (if relevant)
- Browser / OS / Node.js version, etc.

Why Reproduction Steps Matter

Reproduction steps are the single most important element in a bug fix Issue.

Bad example:

Login is broken.

Good example:

## Reproduction Steps
1. Navigate to /login
2. Enter "user@example.com" as the email address
3. Enter "password123" as the password
4. Click the "Login" button
5. Screen goes blank, TypeError appears in console

## Error Message
TypeError: Cannot read properties of undefined (reading 'token')
at AuthService.handleLogin (src/services/AuthService.ts:45)

The more specific the reproduction steps, the more accurately AI can identify and fix the root cause. Always include error messages and stack traces when available.

Specifying Before / After

For bug fixes, describing not just "what to fix" but "what it should look like after fixing" makes a significant difference.

## Expected Behavior (After Fix)
- Successful login: Redirect to dashboard
- Failed login: Show error "Invalid email or password"
- Server error: Show error "Communication failed. Please try again later."

Choosing the Execution Mode

Select the optimal execution mode based on the nature of the bug.

All Phases Mode

Best for:

• Bugs with unknown root cause
• Fixes spanning multiple files
• Bugs requiring thorough test verification
• Bugs caused by design issues

Advantage: The design phase analyzes impact scope, and the testing phase verifies thoroughly. Reliable fixes.

Implementation Only Mode

Best for:

• Bugs with a clear cause and identified fix location
• Fixes contained to 1-2 files
• Bugs verifiable with existing tests
• Urgent bugs requiring fast turnaround

Advantage: Shorter execution time for rapid fixes. Only Planning, Implementation, Documentation, and Report phases run.

Mode Selection Decision Flow

Loading diagram...

When in doubt, "All Phases Mode" is always a safe choice.

Category-Specific Bug Approaches

1. UI Bugs

Characteristics: Layout issues, display glitches, styling problems

Example Issue:

## Bug Summary
The header navigation menu overflows the screen
on mobile display.

## Reproduction Steps
1. Switch to smartphone view (375px) in Chrome DevTools
2. Tap the hamburger menu in the header
3. Navigation menu appears
4. Menu items extend beyond the right edge, causing horizontal scroll

## Target Files
- src/components/Header.tsx
- src/styles/header.module.css

## Expected Behavior
Navigation menu fits within the screen width
with no horizontal scrolling

## Environment
- Chrome 120, iPhone 15 simulation (375 x 812px)

Tip: For UI bugs, screen dimensions and browser information are especially important. Attach screenshots to the Issue when available.

2. Logic Bugs

Characteristics: Calculation errors, conditional logic mistakes, data processing issues

Example Issue:

## Bug Summary
Discount calculation not working correctly. Applying a 10%
discount coupon still shows the original price.

## Reproduction Steps
1. Add "Test Product" ($10.00) to cart
2. Enter coupon code "SAVE10"
3. Click "Apply"
4. "Coupon applied" message appears
5. But total remains $10.00 (expected: $9.00)

## Suspected Cause
The calculateDiscount function in src/services/CartService.ts
appears to calculate the discount amount but may not be applying
it to the total.

## Target Files
- src/services/CartService.ts
- src/hooks/useCart.ts

## Expected Behavior
- After 10% coupon: $10.00 -> $9.00
- Total displayed on screen is updated accordingly

Tip: For logic bugs, specifying concrete input values and expected outputs is essential. Including a suspected cause helps AI investigate more efficiently.

3. Performance Issues

Characteristics: Slow page loads, poor response times, memory leaks

Example Issue:

## Bug Summary
User list page takes 5+ seconds to load.
Becomes significantly slower with 100+ records.

## Reproduction Steps
1. Register 200 users in the test environment
2. Navigate to /admin/users
3. Initial load takes 5-8 seconds
4. Paginating to the next page takes 3-5 seconds each time

## Current Performance
- Initial load: 5-8 seconds
- Page transition: 3-5 seconds

## Target Performance
- Initial load: Under 1 second
- Page transition: Under 500ms

## Suspected Cause
- useEffect fetches all user data (pagination not server-side)
- Possible excessive component re-renders

## Target Files
- src/pages/admin/UserList.tsx
- src/hooks/useUsers.ts
- src/api/users.ts

Tip: For performance issues, concrete metrics (current vs. target) are mandatory.

4. Data Integrity Bugs

Characteristics: Save/load inconsistencies, type mismatches, null/undefined errors

Example Issue:

## Bug Summary
When updating user profile, unchanged fields are
overwritten with null.

## Reproduction Steps
1. Open user profile page
2. Change only the "Display Name" field
3. Click "Save"
4. Reload the page
5. Display name is updated, but phone number and avatar are empty

## Target Files
- src/api/users.ts (updateProfile function)
- src/pages/Profile.tsx

## Expected Behavior
Only changed fields are updated;
unchanged fields retain their existing values

Post-Fix Test Strategy

The worst outcome of a bug fix is "the fix broke something else."

The Importance of Regression Testing

Bug fixes require three types of tests:

Test Type	Purpose	Example
Fix verification	Confirm the bug is fixed	Discount calculation returns correct value
Recurrence prevention	Ensure the same bug doesn't return	Same input patterns work correctly
Regression test	Confirm the fix doesn't break other features	Related calculations still work

Including Test Requirements in Issues

## Test Requirements
### Fix Verification
- 10% coupon application calculates total correctly
- 20% coupon application calculates total correctly

### Regression
- Total calculation without coupon is correct
- Multiple item total calculation is correct
- Shipping calculation is unaffected
- Tax calculation is unaffected

Sumire in Dev Run designs additional regression tests based on impact analysis, beyond what's explicitly specified in the Issue.

Emergency Bug Response Flow

Critical bugs in production demand rapid response.

Emergency Response Flow

Loading diagram...

Emergency Response Tips

1. Use Implementation Only mode: Skip test phases to reduce execution time
2. Keep Issues brief but precise: At minimum include reproduction steps and error messages
3. Minimize fix scope: Do the root cause fix later. Stop the bleeding first
4. Add tests afterward: Create a separate Issue for test additions after the emergency fix

Emergency Issue Example

## URGENT: Payment processing executes twice

## Impact
When users double-click the order confirmation button,
payment executes twice, resulting in double charges.

## Reproduction Steps
1. On checkout page, quickly click "Confirm Order" twice
2. Payment API is called twice

## Expected Fix
- Prevent double-clicks on order confirmation button
- Disable button after first click
- Show loading indicator during processing

## Target File
- src/pages/Checkout.tsx

Tips for More Efficient Bug Fixing

1. Include Error Logs in Issues

## Error Log

TypeError: Cannot read properties of undefined (reading 'map') at UserList (src/components/UserList.tsx:23:18) at renderWithHooks (node_modules/react-dom/...)

Stack traces let AI pinpoint the problem location immediately.

2. Note Recent Related Changes

## Recent Related Changes
- PR #245: Changed user API response format (bug appeared after this change)

When you can guess which change caused the bug, including it improves fix accuracy.

3. Don't Bundle Multiple Bugs in One Issue

One Issue, one bug. Bundling multiple bugs into a single Issue makes the fix too large and reviews too difficult.

Summary

• Reproduction steps are the key to success: Include specific steps, input values, and error messages in Issues
• Choose execution modes wisely: All Phases for unknown causes, Implementation Only for identified issues
• Use category-specific approaches: UI, logic, performance, and data integrity bugs each have their own Issue-writing best practices
• Don't skip regression tests: Include fix verification, recurrence prevention, and regression tests
• Use Implementation Only mode for emergencies: Stop the impact first, add tests later

Bug fixing is unavoidable, but with DevLoop Runner, you can dramatically reduce the time from fix to tested PR. Focus on writing good Issues, and let AI handle the implementation.