Fix Bug

This skill guides you through investigating and fixing bugs in Beluga AI with proper root cause analysis and verification.

Prerequisites

• Bug report or description of unexpected behavior
• Access to relevant logs/error messages
• Ability to reproduce the issue

Steps

1. Understand the Bug

Gather information:

1. Symptoms: What is the observed behavior?
2. Expected: What should happen instead?
3. Reproduction: Steps to trigger the bug
4. Frequency: Always, intermittent, specific conditions?
5. Impact: Severity and affected functionality

2. Reproduce the Issue

Create a minimal reproduction:

func TestBugReproduction(t *testing.T) {
    // Setup that triggers the bug
    component := NewComponent(config)

    // Action that causes the issue
    result, err := component.Process(ctx, input)

    // This assertion should fail (demonstrating the bug)
    require.NoError(t, err) // Currently fails
}

3. Investigate Root Cause

Trace the Code Path

1. Start from the entry point
2. Follow the execution flow
3. Identify where behavior diverges from expected

Check Common Causes

• Nil pointer dereference
• Race condition (concurrent access)
• Resource leak (goroutine, file handle)
• Incorrect error handling
• Missing validation
• Configuration issue
• State mutation
• Context cancellation not respected

Use Debugging Techniques

# Run with race detection
go test -race -v ./pkg/affected/...

# Add verbose logging temporarily
// In code:
log.Printf("DEBUG: value=%v, state=%v", value, state)

# Check OTEL traces if available

4. Document Root Cause

Before fixing, document:

## Root Cause Analysis

**Bug**: [Brief description]

**Root Cause**: [Technical explanation]

**Location**: `pkg/example/file.go:42`

**Why It Happened**: [Context]

**Fix Approach**: [How to fix]

5. Implement the Fix

Write Test First (TDD)

func TestBugFix_IssueXYZ(t *testing.T) {
    // Setup
    component := NewComponent(config)

    // Action
    result, err := component.Process(ctx, input)

    // Assertions that should pass after fix
    require.NoError(t, err)
    assert.Equal(t, expectedResult, result)
}

Apply Minimal Fix

• Fix only what’s broken
• Don’t refactor unrelated code
• Preserve existing behavior for non-bug cases
• Add defensive checks if appropriate

Example Fix Patterns

Nil Check:

// Before
value := obj.Field.Method()

// After
if obj == nil || obj.Field == nil {
    return nil, &Error{Op: "Process", Code: ErrCodeInvalidInput}
}
value := obj.Field.Method()

Race Condition:

// Before
c.state = newState

// After
c.mu.Lock()
c.state = newState
c.mu.Unlock()

Context Cancellation:

// Before
for item := range items {
    process(item)
}

// After
for item := range items {
    select {
    case <-ctx.Done():
        return ctx.Err()
    default:
        process(item)
    }
}

6. Add Regression Test

Ensure the bug cannot recur:

func TestRegression_IssueXYZ(t *testing.T) {
    // Specific conditions that caused the bug
    input := createBugTriggerInput()

    component := NewComponent(config)
    result, err := component.Process(ctx, input)

    // Bug is now fixed
    require.NoError(t, err)
    assert.Equal(t, expected, result)
}

7. Run Quality Checks

# Format and lint
make fmt
make lint

# Run all tests with race detection
make test-race

# Run affected package tests
go test -v -race ./pkg/affected/...

# Run integration tests if applicable
make test-integration

8. Verify Fix

• Original bug is fixed
• Regression test passes
• No new test failures
• Race detection passes
• Related functionality still works

9. Document the Fix

Add to commit message:

fix(package): brief description of fix

Root cause: [explanation]
Fix: [what was changed]

Fixes #123

Validation Checklist

• Bug is reproducible before fix
• Root cause is understood and documented
• Fix is minimal and focused
• Regression test added
• All existing tests pass
• Race detection passes
• Related functionality verified
• Commit message explains the fix

Common Bug Categories

Output

A verified bug fix with:

• Root cause documentation
• Regression test
• Minimal code change
• Passing quality checks