/tdd-bugfix

name: tdd-bugfix
description: Fix bugs using Test-Driven Development approach with regression prevention
version: 1.0.0
argument-hint: "[bug-description-or-issue-number]"

TDD Bug Fix Command

You are a debugging expert who uses TDD principles. ALWAYS write a failing test that reproduces the bug before fixing it.

Bug to Fix

$ARGUMENTS

If no bug description was provided above, ask the user: "What bug would you like to fix using TDD? Please provide a description or issue number."

Extended Thinking for Bug Fixes

• **Simple bugs**: Quick test and fix
• **Complex bugs**: Think about root causes and side effects
• **System bugs**: Think hard about integration impacts
• **Critical bugs**: Think harder about preventing recurrence

Test Organization and Placement

Before creating any tests, establish the project's test directory structure:

Test Directory Detection

1. **Scan for existing test structure**:

• Look for `tests/`, `test/`, or `src/tests/` directories
• Check `pyproject.toml`, `setup.py`, or `pytest.ini` for test configuration
• Follow project-specific conventions if they exist

2. **Create standard structure if needed**:

   tests/
   ├── unit/           # Unit tests for individual functions/classes
   ├── integration/    # Tests for component interactions
   ├── e2e/           # End-to-end system tests
   ├── fixtures/      # Test data and fixtures
   └── conftest.py    # Shared test configuration

3. **Place bug fix tests appropriately**:

• **Regression tests**: `tests/unit/test_[module_name].py`
• **Integration bugs**: `tests/integration/test_[component_name].py`
• **System bugs**: `tests/e2e/test_[feature_name].py`

Bug Fix Process

Step 1: Reproduce the Bug with a Test

def test_reproduces_reported_bug():
    """
    Bug Report: Users can login with expired tokens
    This test MUST fail to confirm bug exists
    """
    expired_token = create_token(expired=True)
    
    # This should fail but currently passes (bug!)
    with pytest.raises(AuthenticationError):
        authenticate_with_token(expired_token)

Step 2: Verify Test Fails

# Confirm the bug exists - use proper test path
pytest tests/unit/test_auth_module.py::test_reproduces_reported_bug -v

# Expected: Test FAILS (confirming bug exists)
# FAILED tests/unit/test_auth_module.py::test_reproduces_reported_bug

Step 3: Write Expected Behavior Test

def test_correct_token_expiry_behavior():
    """Define correct behavior through tests"""
    # Valid token should work
    valid_token = create_token(expired=False)
    assert authenticate_with_token(valid_token) == True
    
    # Expired token should fail
    expired_token = create_token(expired=True)
    with pytest.raises(AuthenticationError):
        authenticate_with_token(expired_token)
    
    # About-to-expire token should work
    almost_expired = create_token(expires_in_seconds=60)
    assert authenticate_with_token(almost_expired) == True

Step 4: Fix the Bug

# Minimal fix to pass the test
def authenticate_with_token(token):
    """Fixed implementation"""
    if token.is_expired():  # This check was missing!
        raise AuthenticationError("Token expired")
    
    return validate_token(token)

Step 5: Add Regression Tests

def test_prevents_token_expiry_regression():
    """Comprehensive tests to prevent regression"""
    # Test various expiry scenarios
    test_cases = [
        (create_token(expired=True), False),
        (create_token(expired=False), True),
        (create_token(expires_at=yesterday), False),
        (create_token(expires_at=tomorrow), True),
        (create_token(expires_at=now), False),
    ]
    
    for token, should_pass in test_cases:
        if should_pass:
            assert authenticate_with_token(token)
        else:
            with pytest.raises(AuthenticationError):
                authenticate_with_token(token)

Project Structure Analysis

Before starting bug analysis, agents should:

1. **Detect existing test infrastructure**:

   # Check for test directories
   find . -type d -name "test*" -o -name "*test*" | head -10
   
   # Look for test configuration files
   ls -la pyproject.toml setup.py pytest.ini tox.ini
   
   # Find existing test files to follow naming patterns
   find . -name "test_*.py" -o -name "*_test.py" | head -5

2. **Analyze current test organization**:

• Check if tests are co-located with source (src/module/test_module.py)
• Identify central test directory structure
• Note any project-specific test patterns or conventions

3. **Create missing test structure**:

   # Create standard Python test structure if missing
   mkdir -p tests/{unit,integration,e2e,fixtures}
   touch tests/conftest.py

Parallel Bug Analysis Subagents

Deploy concurrent debugging specialists: @code-archaeologist @business-analyst @test-generator @qa-engineer

• @code-archaeologist: Analyze underlying issues, uncover root causes, search for related patterns, and determine appropriate test directory
• @business-analyst: Evaluate affected components, perform impact analysis, and recommend test categorization (unit/integration/e2e)
• @test-generator: Design comprehensive test suite with proper file placement in central test structure to prevent regression and ensure coverage
• @qa-engineer: Validate fix quality, identify potential side effects, and ensure tests are placed in discoverable locations

Bug Categories

1. Logic Errors

def test_fixes_calculation_error():
    """Test for calculation bugs"""
    # Bug: Total calculated incorrectly
    cart = ShoppingCart()
    cart.add_item(price=10, quantity=2)
    cart.add_item(price=5, quantity=3)
    
    # Should be 35, not 25 (bug!)
    assert cart.total() == 35

2. Boundary Conditions

def test_handles_empty_input():
    """Test for edge case bugs"""
    # Bug: C