# Systematic Debugging

> This skill should be used when debugging failures, "test is failing", "error I can't explain", "something broke", or any situation requiring structured diagnosis. Provides a 4-phase root-cause approach. Do not use for planning tests or writing new code.

- Skill: `flox/systematic-debugging` (Agent Skill)
- Install (CLI): `npx skillmds@latest add flox/systematic-debugging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/flox/systematic-debugging/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: flox (https://skillmd.com/u/flox)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/flox/systematic-debugging

---


# Systematic Debugging

A structured 4-phase approach to debugging that prevents wild
goose chases and thrashing. Adapted from proven debugging
methodologies for Forge workflows.

## Why Systematic Debugging Matters

**Anti-pattern (debugging thrash):**
- See error
- Try random fix
- Different error appears
- Try another random fix
- Repeat for hours
- Eventually fix by accident

**Systematic approach:**
- Understand root cause before fixing
- Form hypothesis before acting
- Validate hypothesis with evidence
- Fix with confidence

## The Four Phases

### Phase 1: Root Cause Analysis

**Goal:** Understand WHY the error is happening, not just
WHAT the error is.

**Actions:**
1. Read the full error message (don't skim)
2. Identify the exact line/function where failure occurs
3. Trace backward from failure point to find originating cause
4. Ask: "What assumption is being violated?"

**For Python errors:**
- Check stack trace for first application code (not library)
- Look for AttributeError, KeyError, TypeError patterns
- Verify models match migration state

**For TypeScript/JavaScript errors:**
- Read the type error explanation carefully
- Check for null/undefined access patterns
- Look for type mismatches in function calls

**For build errors:**
- Read the first error, not just the last one
- Check for missing imports or dependencies
- Look for version conflicts

**Output:**
```
Root Cause: {Specific reason the error occurs}
Evidence: {Error message, stack trace, or log showing this}
```

### Phase 2: Pattern Recognition

**Goal:** Identify if this is a known pattern or new failure
mode.

**Actions:**
1. Search codebase for similar error patterns
2. Check if this error has appeared in git history (might
   have been fixed before)
3. Look for existing error handling in related code
4. Ask: "Have we seen this category of error before?"

**Common patterns:**
- Path confusion (relative vs absolute paths)
- Context not loaded (accessing data before it exists)
- State mismatch (expecting something that isn't there)
- Git state confusion (expecting branch exists, but doesn't)

**Output:**
```
Pattern: {Known pattern name or "New failure mode"}
Similar cases: {Related errors or fixes in codebase}
```

### Phase 3: Hypothesis Formation

**Goal:** Form testable hypothesis BEFORE making changes.

**Actions:**
1. Based on root cause and pattern, predict what change will
   fix it
2. Identify how to test the hypothesis
3. Consider alternative hypotheses
4. Choose most likely hypothesis first

**Good hypothesis characteristics:**
- Specific (not "something's wrong with X")
- Testable (can verify if correct)
- Explains all symptoms (not just one error)

**Example hypotheses:**
```
❌ Bad: "The file path is wrong"

✅ Good: "The cd command failed silently because directory
doesn't exist, so subsequent commands run in wrong location"
```

**Output:**
```
Hypothesis: {Specific prediction of what will fix it}
Test: {How to verify if hypothesis is correct}
Expected outcome: {What should happen if hypothesis is right}
```

### Phase 4: Fix with Validation

**Goal:** Apply fix and verify it solves the problem without
creating new issues.

**Actions:**
1. Make minimal change to test hypothesis
2. Run test or reproduce error scenario
3. Verify fix solves original problem
4. Check for side effects or new errors
5. If hypothesis wrong, return to Phase 3 with new information

**Validation methods:**
- **Unit tests:** Run specific test that failed
- **Integration tests:** Run full test suite for affected module
- **Manual verification:** Reproduce original error scenario
- **Regression check:** Ensure no new errors introduced

**Anti-patterns:**
- Changing multiple things at once (can't tell what fixed it)
- Not verifying the fix (claiming success without evidence)
- Fixing symptom instead of root cause (band-aid fix)

**Output:**
```
Fix applied: {What changed}
Validation: {Test/verification performed}
Result: {Pass/Fail with evidence}
Side effects: {Any new issues observed}
```

## Debugging Workflow Example

### Scenario: Agent fails to navigate to worktree

**Phase 1: Root Cause**
```
Error: bash: cd: _worktrees/my-feature: No such file or directory

Root Cause: Relative path check succeeded (from repo root),
but cd failed (running from inside worktree).

Evidence:
- test -d "_worktrees/my-feature" returned success
- cd _worktrees/my-feature failed
- pwd showed /home/user/project/_worktrees/other-feature

The agent is already INSIDE a different worktree, so relative
path doesn't exist from there.
```

**Phase 2: Pattern**
```
Pattern: Path confusion — relative vs absolute paths
Similar cases: Common issue when shell CWD isn't repo root
Related: Always use absolute paths for worktree navigation
```

**Phase 3: Hypothesis**
```
Hypothesis: Using absolute paths from git worktree list will
work from any location, unlike relative paths.

Test: Replace relative check with:
  path=$(git worktree list | grep "my-feature" | awk '{print $1}')
  cd "$path"

Expected outcome: cd succeeds regardless of current location
```

**Phase 4: Fix**
```
Fix applied: Updated to use absolute paths from git worktree list

Validation: Ran from three locations:
  - Repo root: ✅ navigated successfully
  - Different worktree: ✅ navigated successfully
  - Target worktree: ✅ detected "already there"

Result: PASS — all scenarios work
Side effects: None observed
```

## When to Use This Pattern

**Always use for:**
- Test failures (don't guess why test failed)
- Runtime errors (understand before fixing)
- Build failures (trace compilation errors)
- Integration issues (API/contract mismatches)

**Optional for:**
- Typos or obvious mistakes (fix directly)
- Linter warnings (follow linter suggestion)
- Documentation updates (no debugging needed)

## Integration with Forge Workflows

**During implementation (`implementation-worker` agent):**
- When tests fail, document debugging phases in commit
  message or PR
- Don't claim "fixed" without validation phase evidence
- Reference which phase revealed the solution

**During code review (`code-reviewer` agent):**
- Check if PRs include validation evidence for fixes
- Verify root cause is addressed, not just symptoms

**In retrospectives:**
- Track patterns that appear repeatedly
- Update context/guidelines when new patterns emerge
- Improve error messages based on root cause insights

## Exceptions and Pragmatic Use

**When to skip systematic debugging:**
- Error message is self-explanatory ("file not found")
- Fix is one-line trivial change
- Debugging would take longer than trying obvious fix

**When to use lightweight version:**
- For simple errors: Root Cause + Fix (skip Pattern and
  Hypothesis)
- For known patterns: Pattern + Fix (leverage knowledge)

**Full 4-phase process recommended for:**
- Mysterious errors without obvious cause
- Errors that reappear after attempted fixes
- System integration failures (multi-component)

## Documenting Debugging Sessions

When debugging reveals important insights, document them:

**In commit messages:**
```
fix(agent): Prevent worktree navigation failures

Root cause: Agents used relative paths which only work from
repo root.
Pattern: Path confusion (relative vs absolute).
Fix: Use absolute paths from git worktree list.
Validated: Tested from repo root, other worktree, and target.
```

**In PR descriptions:**
```
## Debugging Summary
Root cause: {brief}
Fix: {what changed}
Validation: {tests run, output observed}
```

## Summary

| Phase | Question | Output |
|-------|----------|--------|
| 1. Root Cause | WHY is this failing? | Specific reason + evidence |
| 2. Pattern | Have we seen this before? | Pattern name or "new mode" |
| 3. Hypothesis | What change will fix it? | Testable prediction |
| 4. Fix | Does the fix work? | Validation evidence |

**Key principle:** Understand before acting.
Evidence before claiming success.