APAW/.kilo/commands/debug.md

description, mode, model, color, permission

description	mode	model	color	permission
Analyzes errors, bugs, and unexpected behavior, proposes fixes	debug	ollama-cloud/gpt-oss:20b	#EF4444	read edit write bash glob grep task allow allow allow allow allow allow * deny

Debug Command

Systematic debugging workflow for analyzing and fixing bugs in the codebase.

Debugging Philosophy

1. Reproduce - Make the bug happen consistently
2. Isolate - Narrow down the location
3. Understand - Find the root cause
4. Fix - Make minimal, targeted changes
5. Verify - Ensure fix works and no regressions

Workflow

Step 1: Gather Information

• Collect error details:
  • Error messages
  • Stack traces
  • Console output
  • Log files
  • User-reported symptoms
• Ask clarifying questions:
  • When does it occur?
  • What triggers it?
  • What was expected?
  • Environment details?

## Bug Report Template

### Error Message

[Full error/stack trace]

### Context
- Environment: [dev/staging/prod]
- Expected: [What should happen]
- Actual: [What happens]
- Frequency: [Always/Sometimes/Under condition]

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

Step 2: Reproduce Issue

• Create reproduction steps
• Verify bug exists
• Isolate minimal case:
  • Remove dependencies
  • Simplify input
  • Create isolated test

// Minimal reproduction test
describe('Bug reproduction', () => {
  it('should reproduce the bug', () => {
    // Minimal code to trigger bug
    const result = buggyFunction(minimalInput);
    expect(result).toBe(expectedValue); // Should fail
  });
});

Step 3: Locate Bug

• Trace error to source:
  • Follow stack trace
  • Check related files
• Search strategies:

  # Find error source
  grep -r "errorMessage" src/
  
  # Find related function
  grep -r "functionName" src/
  
  # Find similar patterns
  grep -A5 -B5 "pattern" src/file.js
  

• Use logging:

  console.log('Variable state:', variable);
  console.log('Function entry:', params);
  console.log('Decision point:', { condition, value });
  

Step 4: Root Cause Analysis

Identify the category:

• Logic Error: Wrong condition, wrong calculation
• Type Error: Wrong type assumption, null/undefined
• State Error: Incorrect state mutation, race condition
• Integration Error: API mismatch, wrong contract
• Data Error: Corrupt data, missing data
• Environment Error: Config difference, missing dependency

Analyze deeply:

## Root Cause Analysis

### Immediate Cause
[What directly causes the symptom]

### Underlying Cause
[Why the immediate cause exists]

### Trigger Condition
[What makes it happen]

### Example
- Symptom: "Cannot read property 'id' of undefined"
- Immediate: user.id accessed when user is undefined
- Underlying: API returns null for non-existent user
- Trigger: User ID doesn't exist in database

Step 5: Develop Fix

• Propose minimal fix
• Explain reasoning
• Show before/after:

## Fix Proposal

### Change
File: `src/services/user.js:45`

### Before
```javascript
function getUserName(user) {
  return user.name.toUpperCase();
}

After

function getUserName(user) {
  if (!user || !user.name) return 'Unknown';
  return user.name.toUpperCase();
}

Reasoning

1. user can be null when not found
2. user.name can be undefined for incomplete profiles
3. Defensive check prevents crash
4. Default value maintains user experience

### Step 6: Verify Fix

- Run reproduction test (should pass now)
- Run all tests (check for regressions)
- Verify edge cases:
  - Empty inputs
  - Null/undefined
  - Boundary values
  - Error conditions

```markdown
## Verification Results

### Reproduction Test
- Before fix: [FAIL]
- After fix: [PASS]

### Edge Cases
- null input: [PASS] - returns 'Unknown'
- undefined input: [PASS] - returns 'Unknown'
- empty object: [PASS] - returns 'Unknown'
- valid input: [PASS] - returns uppercased name

### Regression Tests
- All existing tests: [PASS]

Step 7: Prevent Recurrence

• Add tests for bug case
• Consider additional validation
• Update documentation if needed
• Add monitoring if applicable

## Prevention

### Tests Added
- `should return Unknown when user is null`
- `should return Unknown when name is undefined`
- `should handle empty user object`

### Monitoring
- Log warning when null user encountered
- Track occurrence rate

Common Bug Patterns

Null/Undefined Errors

// Bad
const name = user.profile.name;

// Good
const name = user?.profile?.name || 'Unknown';

Async/Await Errors

// Bad - Unhandled promise rejection
async function getData() {
  const data = await fetchData();
  return data.value;
}

// Good
async function getData() {
  try {
    const data = await fetchData();
    return data?.value ?? null;
  } catch (error) {
    logger.error('getData failed', { error });
    return null;
  }
}

Race Conditions

// Bad - State changed during async
let cached = null;
async function getData() {
  if (!cached) {
    cached = await fetch(); // Multiple calls might race
  }
  return cached;
}

// Good - Single promise
let cachedPromise = null;
function getData() {
  if (!cachedPromise) {
    cachedPromise = fetch();
  }
  return cachedPromise;
}

Type Assumptions

// Bad - Assumes array
function processItems(items) {
  return items.map(i => i.value);
}

// Good - Validates input
function processItems(items) {
  if (!Array.isArray(items)) return [];
  return items.map(i => i?.value).filter(Boolean);
}

Debug Commands

# Find recent changes
git log --oneline -10

# Find when bug was introduced
git bisect start
git bisect bad HEAD
git bisect good <known-good-commit>

# Search code history
git log -p -S "buggyCode" --all

# Check dependencies
npm ls package-name

Output Format

# Debug Report

## Summary
[Bug description and fix summary]

## Root Cause
- Location: [File:line]
- Type: [Category]
- Cause: [Explanation]

## Fix
[Code change]

## Verification
- Reproduction test: PASS
- Edge cases: PASS
- Regressions: None

## Prevention
- Tests added: [count]
- Monitoring: [if any]