---
name: debugging
description: "A systematic workflow; reproduce -> inspect logs/errors -> isolate cause -> form hypothesis -> test -> fix -> regression test."
---

# Debugging Skill

A systematic workflow: reproduce -> inspect logs/errors -> isolate cause -> form hypothesis -> test -> fix -> regression test.

## Subagents
When you need to delegate sub‑tasks, use the `pi-subagents` skill.

**Example:** When debugging a flaky test, spawn a **scout** to reproduce the issue in a clean environment, another **scout** to analyze the relevant log files, and an **implementer** to apply a targeted fix while a **reviewer** runs the regression suite—all in parallel.

*You may adapt the delegation pattern to fit the exact requirements of the codebase.*

## Workflow

### 1. Reproduce
- Create minimal reproduction case
- Document exact steps
- Verify consistent failure

### 2. Inspect
- Read error messages fully
- Check logs and stack traces
- Examine relevant code paths

### 3. Isolate
- Narrow down the failing component
- Use binary search if needed
- Add temporary logging

### 4. Hypothesize
- Form specific, testable hypotheses
- Prioritize by likelihood
- Consider recent changes

### 5. Test
- Verify each hypothesis
- Use debuggers, prints, or tests
- Document findings

### 6. Fix
- Make minimal targeted change
- Address root cause, not symptom
- Follow existing patterns

### 7. Regression Test
- Run existing test suite
- Add test for the bug
- Verify fix doesn't break other things