debugging-with-tools

<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-resear