Bug Report Skill

Streamlined workflow to handle bug reports from discovery through resolution and commit.

Workflow

1. •Create Issue - Create GitHub issue from bug description
2. •Reproduce - Write test that reproduces the bug
3. •Investigate - Understand root cause
4. •Fix - Implement fix and validate test passes
5. •Iterate - Collaborate with user on fix if needed
6. •Commit - Commit with issue number reference

Step 1: Create GitHub Issue

Use gh issue create to create the issue with a clear title and description:

gh issue create \
  --title "Bug: [brief description]" \
  --body "[Full bug description, reproduction steps, expected vs actual behavior]"

The command returns the issue number (e.g., #123). Store this for the commit message.

Step 2: Write Reproducer Test

Create a test that demonstrates the bug:

• •Location: Add to relevant test file or create new test file in __tests__/
• •Pattern: Test should fail with current code, pass after fix
• •Name: Include the issue number in test name: test('should handle X correctly (fixes #123)', ...)
• •Run: npm run test to verify test fails

Example structure:

test('should handle edge case correctly (fixes #123)', () => {
  // Setup that triggers the bug
  const result = functionWithBug(input);

  // Expected behavior
  expect(result).toEqual(expectedValue);
});

Step 3: Investigate Root Cause

Locate the bug:

1. •Read the error message from the failing test
2. •Use the test to trace through the code
3. •Identify where the logic diverges from expected behavior
4. •Check for: off-by-one errors, missing validation, type mismatches, logic errors

Step 4: Implement Fix

Fix the bug and verify:

1. •Modify the code to fix the issue
2. •Run npm run test - reproducer test should now pass
3. •Run full test suite to ensure no regressions: npm run test:run
4. •If working with configs: run npm run test:configs to validate

Step 5: Iterate with User

If fix needs validation or you hit blockers:

• •Show the user the proposed fix with context
• •Ask for feedback on the approach
• •Adjust based on user input
• •Re-run tests to confirm fix

Step 6: Commit

Create commit with issue number:

git add .
git commit -m "fix: [brief description] (fixes #123)"

Include the issue number in parentheses. The full message should explain why the fix addresses the issue.

Example: fix: validate gross_annual input before calculation (fixes #123)

Tips

• •Test-Driven: Always write failing test before implementing fix
• •Single Issue: Keep fix focused on one bug; if you discover others, create separate issues
• •Verify: Run all relevant test suites (unit tests, config tests) before committing
• •Clear Messages: Commit message should explain the problem and why the fix solves it