debugging-with-tools

What this skill does

<skill_overview>
Random fixes waste time and create new bugs. Always use tools to understand root cause BEFORE attempting fixes. Symptom fixes are failure.
</skill_overview>

<rigidity_level>
MEDIUM FREEDOM - Must complete investigation phases (tools → hypothesis → test) before fixing.

Can adapt tool choice to language/context. Never skip investigation or guess at fixes.
</rigidity_level>

<quick_reference>

| Phase | Tools to Use | Output |
|-------|--------------|--------|
| **1. Investigate** | Error messages, internet-researcher agent, debugger, codebase-investigator | Root cause understanding |
| **2. Hypothesize** | Form theory based on evidence (not guesses) | Testable hypothesis |
| **3. Test** | Validate hypothesis with minimal change | Confirms or rejects theory |
| **4. Fix** | Implement proper fix for root cause | Problem solved permanently |

**FORBIDDEN:** Skip investigation → guess at fix → hope it works
**REQUIRED:** Tools → evidence → hypothesis → test → fix

**Key agents:**
- `internet-researcher` - Search error messages, known bugs, solutions
- `codebase-investigator` - Understand code structure, find related code
- `test-runner` - Run tests without output pollution

</quick_reference>

<when_to_use>
**Use for ANY technical issue:**
- Test failures
- Bugs in production or development
- Unexpected behavior
- Build failures
- Integration issues
- Performance problems

**ESPECIALLY when:**
- "Just one quick fix" seems obvious
- Under time pressure (emergencies make guessing tempting)
- Error message is unclear
- Previous fix didn't work
</when_to_use>

<the_process>

## Phase 1: Tool-Assisted Investigation

**BEFORE attempting ANY fix, gather evidence with tools:**

### 1. Read Complete Error Messages

- Entire error message (not just first line)
- Complete stack trace (all frames)
- Line numbers, file paths, error codes
- Stack traces show exact execution path

### 2. Search Internet FIRST (Use internet-researcher Agent)

**Dispatch internet-researcher with:**
```
"Search for error: [exact error message]
- Check Stack Overflow solutions
- Look for GitHub issues in [library] version [X]
- Find official documentation explaining this error
- Check if this is a known bug"
```

**What agent should find:**
- Exact matches to your error
- Similar symptoms and solutions
- Known bugs in your dependency versions
- Workarounds that worked for others

### 3. Use Debugger to Inspect State

**Claude cannot run debuggers directly. Instead:**

**Option A - Recommend debugger to user:**
```
"Let's use lldb/gdb/DevTools to inspect state at error location.
Please run: [specific commands]
When breakpoint hits: [what to inspect]
Share output with me."
```

**Option B - Add instrumentation Claude can add:**
```rust
// Add logging
println!("DEBUG: var = {:?}, state = {:?}", var, state);

// Add assertions
assert!(condition, "Expected X but got {:?}", actual);
```

### 4. Investigate Codebase (Use codebase-investigator Agent)

**Dispatch codebase-investigator with:**
```
"Error occurs in function X at line Y.
Find:
- How is X called? What are the callers?
- What does variable Z contain at this point?
- Are there similar functions that work correctly?
- What changed recently in this area?"
```

## Phase 2: Form Hypothesis

**Based on evidence (not guesses):**

1. **State what you know** (from investigation)
2. **Propose theory** explaining the evidence
3. **Make prediction** that tests the theory

**Example:**
```
Known: Error "null pointer" at auth.rs:45 when email is empty
Theory: Empty email bypasses validation, passes null to login()
Prediction: Adding validation before login() will prevent error
Test: Add validation, verify error doesn't occur with empty email
```

**NEVER:**
- Guess without evidence
- Propose fix without hypothesis
- Skip to "try this and see"

## Phase 3: Test Hypothesis

**Minimal change to validate theory:**

1. Make smallest change that tests hypothesis
2. Run test/reproduction case
3. Observe result

**If confirmed:** Proceed to Phase 4
**If rejected:** Return to Phase 1 with new information

## Phase 4: Implement Fix

**After understanding root cause:**

1. Write test reproducing bug (RED phase - use test-driven-development skill)
2. Implement proper fix addressing root cause
3. Verify test passes (GREEN phase)
4. Run full test suite (regression check)
5. Commit fix

**The fix should:**
- Address root cause (not symptom)
- Be minimal and focused
- Include test preventing regression

</the_process>

<examples>

<example>
<scenario>Developer encounters test failure, immediately tries "obvious" fix without investigation</scenario>

<code>
Test error:
```
FAIL: test_login_expired_token
AssertionError: Expected Err(TokenExpired), got Ok(User)
```

Developer thinks: "Obviously the token expiration check is wrong"

Makes change without investigation:
```rust
// "Fix" - just check if token is expired
if token.expires_at < now() {
    return Err(AuthError::TokenExpired);
}
```

Commits without testing other cases.
</code>

<why_it_fails>
**No investigation:**
- Didn't read error completely
- Didn't check what `expires_at` contains
- Didn't debug to see token state
- Didn't search for similar issues

**What actually happened:** Token `expires_at` was being parsed incorrectly, always showing future date. The "fix" adds dead code that never runs.

**Result:** Bug not fixed, new dead code added, time wasted.
</why_it_fails>

<correction>
**Phase 1 - Investigate with tools:**

```bash
# 1. Read complete error
FAIL: test_login_expired_token at line 45
Expected: Err(TokenExpired)
Got: Ok(User { id: 123 })
Token: { expires_at: "2099-01-01", ... }
```

**Dispatch internet-researcher:**
```
"Search for: token expiration always showing future date
- Check date parsing bugs
- Look for timezone issues
- Find JWT expiration handling"
```

**Add instrumentation:**
```rust
println!("DEBUG: expires_at = {:?}, now = {:?}, expired = {:?}",
         token.expires_at, now(), token.expires_at < now());
```

**Run test again:**
```
DEBUG: expires_at = 2099-01-01T00:00:00Z, now = 2024-01-15T10:30:00Z, expired = false
```

**Phase 2 - Hypothesis:**
"Token `expires_at` is being set to 2099, not actual expiration. Problem is in token creation, not validation."

**Phase 3 - Test:**
Check token creation code:
```rust
// Found the bug!
fn create_token() -> Token {
    Token {
        expires_at: "2099-01-01".parse()?, // HARDCODED!
        ...
    }
}
```

**Phase 4 - Fix root cause:**
```rust
fn create_token(duration: Duration) -> Token {
    Token {
        expires_at: now() + duration,  // Correct
        ...
    }
}
```

**Result:** Root cause fixed, test passes, no dead code.
</correction>
</example>

<example>
<scenario>Developer skips internet search, reinvents solution to known problem</scenario>

<code>
Error:
```
error: linking with `cc` failed: exit status: 1
ld: symbol(s) not found for architecture arm64
```

Developer thinks: "Must be a linking issue, I'll add flags"

Spends 2 hours trying different linker flags:
```toml
[target.aarch64-apple-darwin]
rustflags = ["-C", "link-arg=-undefined dynamic_lookup"]
# Doesn't work, tries more flags...
```
</code>

<why_it_fails>
**Skipped internet search:**
- This is a common error with known solutions
- Stack Overflow has exact fix
- Official docs explain the issue
- Wasted 2 hours reinventing solution

**Why it happens:** Impatience, thinking "I can figure this out faster"
</why_it_fails>

<correction>
**Dispatch internet-researcher FIRST:**

```
"Search for: 'symbol not found for architecture arm64' Rust linking
- Check Stack Overflow solutions
- Look for Xcode/macOS specific fixes
- Find Cargo configuration for Apple Silicon"
```

**Agent returns (30 seconds):**
```
Found on Stack Overflow (2.4k upvotes):
This occurs when Xcode Command Line Tools aren't installed or outdated.

Solution:
xcode-select --install

Or update existing:
softwareupdate --all --install --force
```

**Apply solution:**
```bash
xcode-