Bug Fix Workflow

Test-Driven Development Approach

When identifying bugs, follow this systematic approach to ensure comprehensive fixes:

1. Identify Why Tests Didn’t Capture the Issue

Before fixing any bug, first understand why the existing test suite failed to catch it:

• Review existing tests for the affected functionality
• Identify gaps in test coverage
• Determine what edge cases or scenarios were missed
• Document the testing blind spot

2. Update Tests to Fail

Create or update tests that demonstrate the bug:

• Write a test that reproduces the exact bug scenario
• Run the test to confirm it fails with the current implementation
• Ensure the test clearly shows the expected vs actual behavior
• Add tests for related edge cases that might have similar issues

3. Fix the Implementation

Once tests are in place and failing:

• Implement the fix to address the root cause
• Ensure the fix is minimal and focused on the specific issue
• Consider whether the fix reveals other potential issues
• Document any assumptions or design decisions

4. Verify the Fix

After implementing the fix:

• Run the new tests to confirm they now pass
• Run the full test suite to ensure no regressions
• Manually verify the fix in the actual system if applicable
• Update documentation if the fix changes behavior

Example Workflow

# 1. Identify the gap
# Review existing tests and identify what's missing
 
# 2. Write failing test
# Add test that demonstrates the bug
task test  # Should fail
 
# 3. Implement fix
# Make minimal changes to fix the root cause
 
# 4. Verify
task test  # Should pass
# Manual verification if needed

Key Principles

• Test First: Always write or update tests before fixing the bug
• Fail First: Confirm tests fail before implementing the fix
• Minimal Changes: Fix only what’s necessary to address the bug
• No Regressions: Ensure existing tests still pass
• Document: Update documentation if behavior changes

When to Skip This Workflow

This workflow may be abbreviated for:

• Trivial typos or formatting issues
• Documentation-only changes
• Configuration updates that don’t affect logic

For all logic bugs, follow the full TDD workflow.