Imported from gyattosai/supersec (.agents/skills/bug-fix/SKILL.md). Install upstream with npx skills add gyattosai/supersec --skill bug-fix. Copyright stays with the author.

Bug Fix Verification

Systematic workflow for verifying bug fixes to ensure quality and prevent regressions.

When to Use This Skill

Use this skill when:

Fixing a reported bug
Creating PR for bug fix
Need to document bug fix verification
Want to ensure fix doesn't introduce regressions
Need structured approach to bug resolution

Why Bug Fix Verification Matters

Problems It Solves

❌ Fixing symptoms instead of root cause
❌ Introducing new bugs while fixing old ones
❌ Incomplete testing of edge cases
❌ No proof that bug is actually fixed
❌ Poor documentation of fix reasoning

Benefits

✅ Confirms bug is truly fixed (not masked)
✅ Documents root cause analysis
✅ Prevents regression with tests
✅ Provides clear evidence for stakeholders
✅ Improves team knowledge of codebase

Bug Fix Workflow

Step 1: Reproduce Before Fix

Critical: Never fix a bug without first reproducing it.

Reproduction Checklist

Document exact steps to reproduce
Capture error message/behavior with screenshots
Note frequency (100% reproducible, intermittent, etc.)
Video recording if UI-related or complex interaction
Identify affected versions/environments
Note any workarounds users have found
Verify bug exists in clean environment (not just local)

Reproduction Documentation Template

## Bug Reproduction

### Steps to Reproduce
1. Navigate to `/dashboard`
2. Click "Export Data" button
3. Select date range: Jan 1 - Dec 31
4. Click "Generate Report"

### Expected Behavior
- Report downloads as CSV file
- File contains all transactions for date range
- Download completes in < 5 seconds

### Actual Behavior
- Error appears: "Failed to generate report"
- Console error: `TypeError: Cannot read property 'map' of undefined`
- No file downloads
- Issue occurs 100% of the time

### Environment
- Browser: Chrome 120.0.6099.109
- OS: macOS 14.2
- User Role: Admin
- Data Size: ~10,000 transactions

### Screenshots
![Error message](screenshots/export-error.png)
![Console error](screenshots/console-error.png)

Step 2: Root Cause Analysis

Investigate WHY the bug occurs, not just WHAT happens.

Investigation Steps

Review Error Logs: Check server logs, browser console, error tracking
Trace Code Path: Follow execution from trigger point to error
Identify Breaking Point: Find exact line/function where bug occurs
Understand Context: Why does code behave this way?
Check Recent Changes: Did recent commit introduce this?
Review Related Code: Are there similar patterns elsewhere?

Root Cause Documentation

## Root Cause Analysis

### Investigation
- Error occurs in `generateReport()` function at line 45
- Function assumes `transactions` array always exists
- When date range returns no results, backend returns `null`
- Frontend doesn't handle `null` case, tries to call `.map()` on `null`

### Root Cause
- Missing null check before array operations
- Backend API doesn't return consistent data structure (sometimes `[]`, sometimes `null`)
- No validation of API response shape

### Why This Wasn't Caught
- Unit tests only covered happy path (data exists)
- Integration tests didn't test empty result scenario
- Backend inconsistency not documented in API contract

Step 3: Implement Fix

Fix the root cause, not the symptom.

Fix Guidelines

Minimal Change: Fix only what's necessary
Defensive Coding: Add validation/guards
Consistent Patterns: Follow existing error handling patterns
Type Safety: Use types to prevent similar bugs
Documentation: Comment non-obvious fixes

Example Fix

// BEFORE (Bug)
function generateReport(transactions) {
  return transactions.map(t => ({
    date: t.date,
    amount: t.amount,
  }));
}

// AFTER (Fixed)
function generateReport(transactions) {
  // Guard against null/undefined from backend
  if (!transactions || !Array.isArray(transactions)) {
    console.warn('No transactions to export');
    return [];
  }

  return transactions.map(t => ({
    date: t.date,
    amount: t.amount,
  }));
}

Step 4: Verify Fix

Prove the bug is fixed through systematic testing.

Verification Checklist

Follow same reproduction steps
Confirm bug no longer occurs
Test edge cases around the fix
Verify no new errors introduced
Check fix works across environments (dev, staging)
Validate fix matches expected behavior

Verification Documentation

## Fix Verification

### Testing Performed
1. ✅ Followed original reproduction steps - bug no longer occurs
2. ✅ Tested with empty date range - shows "No data to export" message
3. ✅ Tested with valid date range - exports successfully
4. ✅ Tested with large dataset (50k+ transactions) - works correctly
5. ✅ Tested in Chrome, Firefox, Safari - all working
6. ✅ Tested on staging environment - fix confirmed

### Edge Cases Tested
- Empty result set → Shows appropriate message
- Null response from API → Handled gracefully
- Single transaction → Exports correctly
- Malformed transaction data → Logs error, doesn't crash

### No New Issues
- ✅ No console errors
- ✅ No memory leaks
- ✅ No performance degradation
- ✅ Other export features still work

Step 5: Add Tests to Prevent Regression

Critical: Every bug fix must include tests.

Test Requirements

Test that reproduces original bug (should pass after fix)
Tests for edge cases discovered during investigation
Integration test if bug involved multiple components
Update existing tests if they need to handle new scenarios

Example Tests

describe('generateReport', () => {
  // Test that reproduces original bug
  it('should handle null transactions gracefully', () => {
    const result = generateReport(null);
    expect(result).toEqual([]);
    expect(console.warn).toHaveBeenCalledWith('No transactions to export');
  });

  // Edge cases
  it('should handle undefined transactions', () => {
    const result = generateReport(undefined);
    expect(result).toEqual([]);
  });

  it('should handle empty array', () => {
    const result = generateReport([]);
    expect(result).toEqual([]);
  });

  it('should handle single transaction', () => {
    const transactions = [{ date: '2025-01-01', amount: 100 }];
    const result = generateReport(transactions);
    expect(result).toHaveLength(1);
    expect(result[0]).toEqual({ date: '2025-01-01', amount: 100 });
  });

  // Original happy path (should still work)
  it('should transform multiple transactions correctly', () => {
    const transactions = [
      { date: '2025-01-01', amount: 100 },
      { date: '2025-01-02', amount: 200 },
    ];
    const result = generateReport(transactions);
    expect(result).toHaveLength(2);
  });
});

Step 6: Document in PR

Comprehensive PR description for bug fixes.

PR Template for Bug Fixes

## Bug Fix: [Brief Description]

**Ticket**: #123 / ENG-456 / JIRA-789

### Problem
[Clear description of the bug]

### Reproduction Steps (Before Fix)
1. [Step 1]
2. [Step 2]
3. [Error occurs]

**Expected**: [What should happen]
**Actual**: [What happened instead]

### Root Cause
[Detailed explanation of why bug occurred]

- Where: `src/utils/report.ts`, line 45
- Why: Null check missing before array operation
- Impact: Affects all users trying to export with empty date ranges

### Solution
[Explanation of how fix works]

- Added null/undefined check before array operations
- Return empty array instead of crashing
- Added user-facing warning message
- Updated API response handling to be more defensive

### Fix Verification (After)
1. ✅ Followed reproduction steps - bug no longer occurs
2. ✅ Tested edge cases (null, undefined, empty array)
3. ✅ Tested across browsers (Chrome, Firefox, Safari)
4. ✅ Verified on staging environment
5. ✅ No new console errors or warnings

### Test Coverage
- Added unit tests for null/undefined handling
- Added tests for empty array edge case
- Updated integration tests for export feature
- All existing tests still passing

**Coverage**: +15 lines covered, 0 lines uncovered

### Regression Prevention
- [x] Tests added that would catch this bug if reintroduced
- [x] Similar patterns checked in codebase (found 2, fixed in this PR)
- [x] Documentation updated to note API response inconsistency

### Screenshots/Evidence
**Before (Bug)**:
![Error state](screenshots/before-error.png)

**After (Fixed)**:
![Success state](screenshots/after-success.png)
![Empty state](screenshots/after-empty.png)

### Deployment Notes
- No migrations required
- No environment variable changes
- Safe to deploy immediately
- Rollback: Revert this commit

### Related Issues
- Closes #123
- Related to #456 (similar null handling issue)

Common Pitfalls to Avoid

During Investigation

❌ Assuming you know the cause without verifying
❌ Fixing symptoms instead of root cause
❌ Not checking if similar bugs exist elsewhere
❌ Skipping reproduction in clean environment

During Implementation

❌ Making changes beyond fixing the bug
❌ Refactoring unrelated code in bug fix PR
❌ Adding features while fixing bugs
❌ Not handling all edge cases discovered

During Verification

❌ Only testing happy path after fix
❌ Not testing in multiple environments
❌ Skipping regression testing
❌ Not documenting what was tested

During Documentation

❌ Vague PR descriptions ("Fixed bug")
❌ Not explaining root cause
❌ Missing before/after evidence
❌ Not linking to original bug report

Bug Fix Quality Standards

Minimum Requirements

✅ Root cause identified and documented
✅ Fix is minimal and targeted
✅ Tests added to prevent regression
✅ Verification documented with evidence
✅ No new bugs introduced
✅ Works across all supported environments

Excellence Indicators

✅ Similar patterns checked and fixed
✅ Multiple edge cases tested
✅ Performance impact measured
✅ Team knowledge shared (wiki/docs updated)
✅ Preventive measures suggested

Automation Support

Bug Fix PR Template

Create .github/PULL_REQUEST_TEMPLATE/bug_fix.md:

## Bug Fix

**Ticket**: [Ticket number/link]

### Problem
[Description of bug]

### Reproduction Steps (Before Fix)
1.
2.
3.

**Expected**:
**Actual**:

### Root Cause
[Explanation of why bug occurred]

### Solution
[How fix works]

### Verification (After)
- [ ] Original reproduction steps no longer trigger bug
- [ ] Edge cases tested
- [ ] Tested in multiple browsers/environments
- [ ] No new errors or warnings

### Test Coverage
- [ ] Tests added for bug scenario
- [ ] Tests added for edge cases
- [ ] All existing tests passing

### Screenshots
**Before**: [Screenshot]
**After**: [Screenshot]

GitHub Actions for Bug Fix PRs

name: Bug Fix Verification
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  verify-bug-fix:
    if: contains(github.event.pull_request.labels.*.name, 'bug')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check PR description
        run: |
          PR_BODY="${{ github.event.pull_request.body }}"
          if [[ ! "$PR_BODY" =~ "Root Cause" ]]; then
            echo "::error::Bug fix PR must document root cause"
            exit 1
          fi
          if [[ ! "$PR_BODY" =~ "Verification" ]]; then
            echo "::error::Bug fix PR must document verification steps"
            exit 1
          fi

      - name: Run tests
        run: npm test

      - name: Check test coverage
        run: |
          COVERAGE=$(npm test -- --coverage --json | jq '.total.lines.pct')
          if (( $(echo "$COVERAGE < 90" | bc -l) )); then
            echo "::warning::Test coverage is below 90%"
          fi

Success Criteria

Bug Fix is Complete When

✅ Bug can no longer be reproduced
✅ Root cause is understood and documented
✅ Fix is minimal and targeted
✅ Tests prevent regression
✅ Edge cases are handled
✅ Works in all environments
✅ PR documentation is comprehensive
✅ No new issues introduced

Related Skills

universal-verification-pre-merge - Pre-merge verification checklist
universal-verification-screenshot - Visual verification for UI bugs
universal-debugging-systematic-debugging - Systematic debugging methodology
universal-debugging-root-cause-tracing - Root cause analysis techniques
universal-testing-testing-anti-patterns - Testing patterns to avoid

About