| name | bug-fix-workflow |
| description | Fix bugs using the two-commit structure with failing test first. Use when fixing bugs, addressing issues, or correcting incorrect behavior. |
| user-invocable | true |
Bug Fix Workflow
Bug fixes use a two-commit structure that proves the bug exists before fixing it.
The Two-Commit Structure
Commit 1: Reproduce the Bug
test: reproduce <issue description>
Adds a failing test that demonstrates the bug:
- Must fail BEFORE the fix
- Must pass AFTER the fix
- Prevents future regressions
Commit 2: Fix the Bug
fix: <description of what was fixed>
This commit:
- Fixes the actual bug
- Updates the test if needed
- May include additional related fixes
Why This Structure?
- Proves the bug exists before the fix
- Validates the fix actually resolves the issue
- Prevents regressions by leaving the test in place
- Makes review easier by separating reproduction from fix
Workflow Steps
1. Understand the Bug
- Read the issue/report carefully
- Identify expected vs actual behavior
- Determine the root cause
2. Write a Failing Test
test('issue #123: handles empty input correctly', () => {
const result = processInput('');
expect(result).toBe('default');
});
3. Verify the Test Fails
npm test -- --grep "issue #123"
4. Commit the Failing Test
git add .
git commit -m "test: reproduce empty input handling (issue #123)"
5. Implement the Fix
Make the minimal changes needed to fix the bug.
6. Verify the Test Passes
npm test -- --grep "issue #123"
npm test
7. Commit the Fix
git add .
git commit -m "fix: handle empty input by returning default value
The processInput function was not checking for empty strings
before attempting to parse, causing an exception."
Commit Message Guidelines
Test Commit
test: reproduce <brief description>
- Reference issue number if applicable
- Describe what the test checks
- Note expected vs actual behavior
Fix Commit
fix: <what was fixed>
<Why the bug occurred>
<What the fix does>
Common Mistakes
- Don't combine test and fix in one commit
- Don't write a passing test first - it must fail initially
- Don't skip the test for "obvious" fixes
- Don't forget to run all tests before the fix commit
Checklist
