Fix Bug

基于根本原因分析的漏洞调查与修复工作流

SKILL.md

--- frontmatter

name: Fix Bug
description: Bug investigation and fix workflow with root cause analysis
personas:
  - backend-developer

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:

•Symptoms: What is the observed behavior?
•Expected: What should happen instead?
•Reproduction: Steps to trigger the bug
•Frequency: Always, intermittent, specific conditions?
•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

•Start from the entry point
•Follow the execution flow
•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

bash

# 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:

markdown

## 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

bash

# 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

9. Document the Fix

Add to commit message:

code

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

Category	Symptoms	Typical Fix
Nil pointer	Panic	Add nil checks
Race condition	Intermittent failures	Add mutex/atomic
Resource leak	Memory growth	Add defer cleanup
Error handling	Silent failures	Check and propagate errors
Context	Hanging operations	Respect ctx.Done()
Validation	Invalid state	Add input validation

Output

A verified bug fix with:

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