test-first-bugs

Test-first bug fixing

Enforce a disciplined bug-fixing workflow that prevents regression and parallelizes fix attempts.

Core workflow

When a bug is reported, follow these steps in order:

Phase 1: Reproduce and document

1. Understand the bug, Gather details about expected vs actual behavior
2. Identify the test location, Determine where tests live in the project (check for tests/, __tests__/, spec/, *.test.*, *.spec.* patterns)
3. Write a failing test, Create a test that demonstrates the bug

Phase 2: Fix with subagents

1. Launch fix subagents, Use the Task tool with subagent_type=general-purpose to attempt fixes
2. Run the test, Verify the fix by running the specific test
3. Iterate if needed, If test still fails, launch additional subagents with new approaches

Phase 3: Verify and complete

1. Run full test suite, Ensure no regressions were introduced
2. Report success, Confirm the bug is fixed with passing test as proof

Writing the failing test

Test naming convention

Name the test to describe the bug:

# Python (pytest)
def test_user_login_fails_when_email_has_uppercase():
    ...

# Python (unittest)
def test_should_handle_empty_input_without_crashing(self):
    ...

// JavaScript (Jest/Vitest)
it('should not crash when input array is empty', () => { ... });
test('handles special characters in username', () => { ... });

// TypeScript
describe('UserService', () => {
  it('returns null when user not found instead of throwing', () => { ... });
});

Test structure

Every bug reproduction test follows this pattern:

def test_bug_description():
    # 1. ARRANGE - Set up the conditions that trigger the bug
    input_data = create_problematic_input()

    # 2. ACT - Perform the action that causes the bug
    result = function_under_test(input_data)

    # 3. ASSERT - Verify the expected (correct) behavior
    assert result == expected_value  # This should FAIL initially