Systematic Bug Fixing

A methodical approach to debugging that prioritizes understanding over guessing.

The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

Rule Zero: Verify Bug Reports Before Fixing

Bug reports, QA comments, and card descriptions can be WRONG. Verify first.

Before fixing any reported issue:

Step	Action
1	Read the actual code - Understand current implementation
2	Verify the claim - Is it actually a bug or misunderstanding?
3	Check official docs - Framework docs, API references, etc.
4	Trace execution flow - Hook order, data flow, lifecycle
5	Only fix if confirmed - Push back with evidence if not a real bug

Common false positives:

• Hook timing claims without understanding framework execution order
• "Missing" features that exist but need to be enabled
• "Bugs" that are actually intended behavior
• Performance issues based on code reading, not profiling

If the bug report is wrong: Don't fix it. Comment back explaining why it's not actually a bug.

Attempting solutions without understanding the underlying problem leads to:

• Wasted time (2-3 hours vs 15-30 minutes)
• New bugs introduced
• Original issue not actually fixed
• Technical debt accumulation

When to Apply This Methodology

Use for any technical issue:

• Test failures
• Production bugs
• Unexpected behavior
• Performance problems
• Build failures
• Integration issues

Apply especially when:

• Under time pressure
• Quick fixes seem obvious
• After multiple failed attempts
• Understanding is incomplete

Four Sequential Phases

Phase 1: Root Cause Investigation

Complete these steps BEFORE proposing any fix:

1. Read Error Messages Thoroughly

# Don't skip past errors - they often contain solutions
# Note: line numbers, file paths, error codes

# BAD: Glancing at error
"Something about undefined..."

# GOOD: Full analysis
Error: Cannot read property 'name' of undefined
    at getUserData (src/services/user.js:45:23)
    at async handleRequest (src/api/handler.js:12:15)
# -> Issue is in getUserData at line 45, 'name' accessed on undefined value

2. Reproduce Consistently

// Document exact reproduction steps
/*
REPRODUCTION STEPS:
1. Login as test user (test@example.com)
2. Navigate to /dashboard
3. Click "Export" button
4. Select date range > 30 days
5. Click "Generate"
ERROR: "Cannot read property 'map' of undefined"

ENVIRONMENT:
- Browser: Chrome 120
- Node: 18.17.0
- OS: macOS 14.1
*/

3. Check Recent Changes

# What changed recently?
git log --oneline -20
git diff HEAD~5..HEAD -- src/

# Who touched the failing file?
git blame src/services/user.js

# When did it last work?
git bisect start
git bisect bad HEAD
git bisect good v1.2.3

4. Trace Data Flow Backward

// Work backward through call stack to find WHERE bad values originate

// Error occurs here:
function displayUser(user) {
  return user.name.toUpperCase(); // user is undefined!
}

// Trace back: Who calls displayUser?
function renderProfile() {
  const user = getCurrentUser(); // Returns undefined!
  return displayUser(user);
}

// Trace back: Why does getCurrentUser return undefined?
function getCurrentUser() {
  return userCache.get(userId); // userId is null!
}

// ROOT CAUSE FOUND: userId is null before cache lookup

5. Gather Evidence in Multi-Component Systems

// For systems with multiple layers, add diagnostic logging

// API -> Service -> Database
async function debugDataFlow() {
  console.log('[API] Request received:', req.body);

  const serviceResult = await service.process(data);
  console.log('[SERVICE] Result:', serviceResult);

  const dbResult = await db.save(serviceResult);
  console.log('[DB] Saved:', dbResult);

  // Identify which layer fails
}

Phase 2: Pattern Analysis

Before forming solutions:

1. Find Working Examples

// Look for similar code that WORKS in the codebase

// Broken:
const users = await fetchUsers();
users.map(u => u.name); // Fails when users is undefined

// Working (in another file):
const posts = await fetchPosts();
if (!posts || posts.length === 0) {
  return [];
}
posts.map(p => p.title); // Works because of guard clause

2. Compare Against References

// Read documentation/examples COMPLETELY

// API Documentation says:
// fetchUsers() returns Promise<User[] | null>
// Returns null when: user not authenticated, rate limited

// Your assumption was:
// fetchUsers() always returns User[]

// FIX: Handle null case
const users = await fetchUsers();
if (!users) {
  throw new AuthenticationError('Not authenticated');
}

3. List All Differences

| Aspect | Working Code | Broken Code |
|--------|--------------|-------------|
| Null check | Yes | No |
| Error handling | try/catch | None |
| Async handling | await | Missing await |
| Input validation | Validates | Trusts input |

Phase 3: Hypothesis and Testing

Apply scientific methodology:

1. Form Single Hypothesis

// State clearly: "I think X is the root cause because Y"

// HYPOTHESIS:
// The error occurs because fetchUsers() returns null when the
// session token expires, but we don't handle the null case.
// Evidence: Error only happens after ~30 minutes of inactivity
// (matching our 30-minute session timeout).

2. Test Minimally

// Make the SMALLEST possible change to test your theory
// One variable at a time

// TEST:
const users = await fetchUsers();
console.log('fetchUsers returned:', users, typeof users);
// If null: hypothesis confirmed
// If array: hypothesis wrong, form new hypothesis

3. Verify or Reject

// If test confirms hypothesis -> Phase 4
// If test rejects hypothesis -> Form new hypothesis

// DON'T: Add multiple fixes hoping one works
// DO: Test one thing, understand result, proceed logically

Phase 4: Implementation

Fix the ROOT CAUSE, not symptoms:

1. Create Failing Test Case

// Write test BEFORE fix
describe('fetchUsers', () => {
  it('handles null response from expired session', async () => {
    // Arrange
    mockSession.expire();

    // Act & Assert
    await expect(getUserList()).rejects.toThrow('Session expired');
  });
});

2. Implement Single Fix

// BAD: Multiple changes at once
async function getUserList() {
  try {
    const users = await fetchUsers();
    if (!users) throw new Error('No users');
    if (!Array.isArray(users)) users = [users];
    return users.filter(u => u.active).map(u => u.name);
  } catch (e) {
    console.error(e);
    return [];
  }
}

// GOOD: Address only the identified root cause
async function getUserList() {
  const users = await fetchUsers();
  if (!users) {
    throw new SessionExpiredError('Session expired, please login again');
  }
  return users.map(u => u.name);
}

3. Verify Fix

# Run specific test
npm test -- --grep "handles null response"

# Run related tests
npm test -- src/services/user.test.js

# Run full suite to check for regressions
npm test

4. Handle Failed Fixes

After 2 unsuccessful attempts:
  -> Return to Phase 1, gather more evidence

After 3+ failures:
  -> Question whether the architecture is fundamentally sound
  -> Discuss with team before continuing
  -> Consider if refactoring is needed

Red Flags - Return to Phase 1

Stop immediately if you think:

Thought	Why It's Wrong
"Quick fix for now, investigate later"	You'll never investigate later
"Just try changing X and see if it works"	Random changes introduce new bugs
"It's probably X, let me fix that"	"Probably" means you don't know
"I don't fully understand but this might work"	Guaranteed to fail or cause new issues

Common Bug Categories

Null/Undefined Errors

// Problem: Accessing property on null/undefined
user.profile.avatar.url

// Solutions:
// 1. Optional chaining
user?.profile?.avatar?.url

// 2. Guard clauses
if (!user?.profile?.avatar) return defaultAvatar;

// 3. Nullish coalescing
const url = user?.profile?.avatar?.url ?? defaultAvatar;

Async/Await Issues

// Problem: Missing await
async function loadData() {
  const data = fetchData(); // Missing await!
  console.log(data); // Promise, not data
}

// Problem: Parallel vs Sequential
// BAD: Sequential (slow)
const user = await fetchUser();
const posts = await fetchPosts();
const comments = await fetchComments();

// GOOD: Parallel (fast)
const [user, posts, comments] = await Promise.all([
  fetchUser(),
  fetchPosts(),
  fetchComments(),
]);

Race Conditions

// Problem: State changes during async operation
async function updateUser() {
  const user = this.state.user; // Captured at start
  const updated = await api.updateUser(user);
  this.setState({ user: updated }); // Overwrites changes made during await!
}

// Solution: Use functional update
this.setState(prevState => ({
  user: { ...prevState.user, ...updated }
}));

Off-by-One Errors

// Problem: Array bounds
for (let i = 0; i <= array.length; i++) { // <= should be <
  array[i]; // Undefined on last iteration
}

// Problem: Pagination
const page = 1;
const offset = page * pageSize; // Should be (page - 1) * pageSize

State Mutation

// Problem: Mutating state directly
const newArray = oldArray;
newArray.push(item); // Mutates oldArray too!

// Solution: Create new references
const newArray = [...oldArray, item];
const newObject = { ...oldObject, newProperty: value };

Debugging Tools

Browser DevTools

// Breakpoints
debugger; // Pauses execution

// Console methods
console.log(obj);
console.table(arrayOfObjects);
console.trace(); // Shows call stack
console.time('operation');
// ... operation
console.timeEnd('operation');

Node.js Debugging

# Inspect mode
node --inspect src/index.js

# Break on first line
node --inspect-brk src/index.js

# Debug tests
node --inspect-brk node_modules/.bin/jest --runInBand

Git Bisect

# Find the commit that introduced the bug
git bisect start
git bisect bad                 # Current commit is bad
git bisect good v1.2.0         # This version was good
# Git checks out middle commit
# Test it, then:
git bisect good  # or
git bisect bad
# Repeat until git finds the bad commit
git bisect reset  # Return to original state

Debugging Checklist

• Can reproduce the issue consistently
• Read complete error message and stack trace
• Checked recent changes (git log/blame)
• Identified root cause (not just symptoms)
• Found working example for comparison
• Formed testable hypothesis
• Fix addresses root cause only
• Created regression test
• Tested edge cases
• No new issues introduced
• Documented the fix

Post-Fix Actions

1. Add regression test - Prevent issue from returning
2. Update documentation - If behavior was unclear
3. Consider related code - Same bug elsewhere?
4. Add monitoring - Detect if it happens again
5. Share learnings - Help team avoid similar issues