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.
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.
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:
Read the full error message (don't skim)
Identify the exact line/function where failure occurs
Trace backward from failure point to find originating cause
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:
Search codebase for similar error patterns
Check if this error has appeared in git history (might
have been fixed before)
Look for existing error handling in related code
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:
Based on root cause and pattern, predict what change will
fix it
Identify how to test the hypothesis
Consider alternative hypotheses
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:
Make minimal change to test hypothesis
Run test or reproduce error scenario
Verify fix solves original problem
Check for side effects or new errors
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.
