claudekit/.claude/commands/fix.md

/fix - Bug Fix Workflow

Purpose

Smart debugging and bug fixing workflow that analyzes errors, identifies root causes, implements fixes, and adds regression tests.

Usage

/fix [error message, bug description, or issue reference]

Arguments

• $ARGUMENTS: Error message, stack trace, bug description, or issue number

---

Analyze and fix the following issue: $ARGUMENTS

Workflow

Phase 1: Error Analysis

1. Parse Error Information

   • Extract error type and message
   • Parse stack trace if available
   • Identify the failing location

2. Gather Context

   • When does this error occur?
   • What triggers it?
   • Is it reproducible?
   • When did it start happening?

3. Check for Known Patterns

   • Common error patterns
   • Similar issues in codebase
   • Recent changes that might have caused it

Phase 2: Root Cause Investigation

1. Trace Execution

   • Follow the code path to the error
   • Identify state at each step
   • Find where expectations diverge

2. Form Hypotheses

   • List possible causes ranked by likelihood
   • Identify minimal tests to validate each

3. Validate Hypothesis

   • Test the most likely cause first
   • Confirm root cause before fixing
   • Don't fix symptoms only

Phase 3: Search Related Code

1. Find Similar Code

   • Search for similar patterns
   • Check if same bug exists elsewhere
   • Identify shared code that might be affected

2. Review Recent Changes

   git log --oneline -20
   git blame [file]
   

Phase 4: Implement Fix

1. Develop Minimal Fix

   • Fix the root cause, not symptoms
   • Keep changes minimal and focused
   • Consider edge cases

2. Add Defensive Code (if appropriate)

   • Input validation
   • Null checks
   • Error handling

3. Update Related Code (if needed)

   • Fix same issue in similar code
   • Update shared utilities

Phase 5: Verification

1. Test the Fix

   • Verify original error is resolved
   • Check related functionality
   • Run existing test suite

2. Add Regression Test

   • Write test that would have caught this bug
   • Include edge cases discovered
   • Ensure test fails without fix

3. Run Full Test Suite

   # Python
   pytest -v
   
   # TypeScript
   pnpm test
   

Phase 6: Documentation

1. Document the Fix

   • What was the issue
   • What caused it
   • How it was fixed

2. Update Comments (if needed)

   • Add clarifying comments
   • Document non-obvious behavior

Output

Bug Fix Summary

## Bug Fix Complete

### Issue
[Original error/bug description]

### Root Cause
[Explanation of what caused the bug]

### Location
`path/to/file.ts:42` - [function/method name]

### Fix Applied

**Before:**
```[language]
// Problematic code

After:

// Fixed code

Explanation

[Why this fix resolves the issue]

Regression Test Added

path/to/test.ts - test_[scenario]

Verification

• Original error no longer occurs
• Existing tests pass
• New regression test passes
• No new issues introduced

Related Areas Checked

• path/to/similar.ts - No similar issue

Commands to Verify

pytest tests/test_file.py -v
# or
pnpm test path/to/file.test.ts

## Common Fix Patterns

### Null/Undefined Access

```typescript
// Before
const name = user.profile.name;

// After
const name = user?.profile?.name ?? 'Unknown';

Missing Error Handling

# Before
data = json.loads(response.text)

# After
try:
    data = json.loads(response.text)
except json.JSONDecodeError as e:
    logger.error(f"Invalid JSON response: {e}")
    raise InvalidResponseError("Failed to parse response")

Race Condition

// Before
const data = await fetchData();
setState(data); // May be unmounted

// After
useEffect(() => {
  let cancelled = false;
  fetchData().then(data => {
    if (!cancelled) setState(data);
  });
  return () => { cancelled = true; };
}, []);

Off-by-One Error

# Before
for i in range(len(items) + 1):  # IndexError
    process(items[i])

# After
for i in range(len(items)):
    process(items[i])
# or
for item in items:
    process(item)

Example

Input: /fix TypeError: Cannot read property 'email' of undefined in UserService.ts:45

Output:

1. Analysis: User object is undefined when accessed
2. Root cause: async fetch didn't await, user not loaded yet
3. Fix: Add null check and proper async handling
4. Regression test: Test for case when user is not loaded

Variations

Modify behavior via CLAUDE.md:

• Set required test coverage for fixes
• Define severity levels for bugs
• Configure error reporting format
• Set required review process