Bug Fixing

Bug Fixing Skill

Overview

This skill provides a systematic approach to debugging and fixing bugs efficiently while preventing regressions.

The Bug Fixing Process

Phase 1: Reproduction (Critical!)

Goal: Create a reliable reproduction case.

1.1 Gather Information

□ Bug report details: What happened vs expected
□ Environment: OS, browser, version, config
□ Steps to reproduce (user's description)
□ Error messages and stack traces
□ Logs (application, system, browser console)
□ Recent changes (git history, deployments)
□ Frequency: Always, sometimes, once?

1.2 Reproduce Locally

□ Set up same environment
□ Follow reported steps exactly
□ Try variations of steps
□ Test on different browsers/devices (if applicable)
□ Test with different data/inputs

If you can't reproduce:

• Ask for more details
• Check production logs more carefully
• Add more logging
• Consider race conditions or timing issues
• Check for environment-specific issues

1.3 Document Reproduction

## Bug: [Brief description]

### Reproduction Steps
1. [Step 1]
2. [Step 2]
3. [Step 3]

### Expected
[What should happen]

### Actual
[What actually happens]

### Environment
- OS: [e.g., Ubuntu 22.04]
- Browser: [e.g., Chrome 120]
- Version: [commit hash or version]
- Config: [relevant settings]

Phase 2: Investigation & Isolation

Goal: Find the root cause, not just the symptom.

2.1 Binary Search Method

1. Identify entry point (user action/API call)
2. Add logging/checkpoints throughout code path
3. Run reproduction
4. Narrow down to specific function/line
5. Repeat until root cause found

2.2 Debugging Techniques

Logging Strategy:

// Add strategic logging
func processOrder(order *Order) error {
    log.Printf("[DEBUG] Processing order: %+v", order)
    
    if order.Total 

# Race detection
go run -race main.go

# Profile
import "runtime/pprof"

Rust

# Debug with gdb/lldb
cargo build
gdb target/debug/myapp

# Backtrace on panic
RUST_BACKTRACE=1 cargo run

# Use log crate
log::debug!("Variable x = {}", x);

TypeScript/JavaScript

# Node.js debugging
node --inspect-brk server.ts

# Chrome DevTools
# 1. Add 'debugger;' statements
# 2. Open DevTools
# 3. Sources tab → find file

# Console logging strategies
console.log("Debug:", { user, order, config });
console.table(data);
console.trace("Called from:");

Best Practices

1. Add Logging Before Fixing

// Temporary logging
log.Printf("[BUG] Variable state: x=%v, y=%v", x, y)
log.Printf("[BUG] Stack trace: %s", debug.Stack())

2. Create Minimal Reproduction

// Create test case that reproduces the bug
func TestBug_MissingEmail(t *testing.T) {
    // Minimal setup to reproduce
    user := &User{ID: "1"}
    err := sendEmail(user, "Hello")
    
    // Before fix: should fail
    // assert.Error(t, err)
    
    // After fix: should handle gracefully
    assert.NoError(t, err)
}

3. Document the Fix

// Fix for GitHub issue #123
// Users created via OAuth without email were causing nil pointer
// on checkout. Now we gracefully handle missing emails.
func (s *Service) ProcessOrder(user *User, order *Order) error {
    if user.Email == "" {
        return ErrEmailRequired
    }
    // ...
}

4. Prevent Future Bugs

// Add validation at creation time
type User struct {
    Email string `validate:"required,email"`
}

// Or database constraint
// ALTER TABLE users ADD CONSTRAINT email_required CHECK (email IS NOT NULL AND email != '');

When to Use

Use this skill when:

• Debugging a reported bug
• Investigating production issues
• Writing regression tests
• Reviewing bug fixes
• Preventing bugs through design

Common Anti-patterns to Avoid

// DON'T: Fix the symptom
func process(user *User) {
    if user == nil {
        return // Silent failure - bad!
    }
}

// DO: Fix the root cause
func process(user *User) error {
    if user == nil {
        return fmt.Errorf("user is nil")
    }
    // ...
}

// DON'T: Comment out code instead of fixing
// if (buggyCondition) { ... }

// DO: Fix properly or delete entirely

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Jonathan0823
• Source: Jonathan0823/opencode-config
• License: MIT

Install and usage instructions live in the source repository linked above.