Use when encountering any bug, test failure, or unexpected behaviour, before proposing any fixes. Four-phase root-cause protocol with hard 3-attempt circuit breaker. Enhances the bug-hunter agent with structured investigation. Triggers on "bug", "error", "failing", "crash", "debug", "broken", "why isn't", "not working".
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Use when encountering any bug, test failure, or unexpected behaviour, before proposing any fixes. Four-phase root-cause protocol with hard 3-attempt circuit breaker. Enhances the bug-hunter agent with structured investigation. Triggers on "bug", "error", "failing", "crash", "debug", "broken", "why isn't", "not working".
license
MIT
metadata
{"author":"NodeJS-Starter-V1 โ adapted from obra/superpowers (MIT)","version":"1.0.0","locale":"en-AU"}
Systematic Debugging
Adapted from obra/superpowers โ MIT. Enhances the bug-hunter agent with a structured 4-phase investigation protocol and a hard 3-attempt circuit breaker.
The Iron Law
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
If you haven't completed Phase 1, you cannot propose fixes.
When to Use
Any technical issue:
Failing vitest or pytest tests
FastAPI endpoint errors (500, 422, 401, 403)
React component rendering issues
TypeScript type errors
Docker / PostgreSQL connection failures
LangGraph agent unexpected behaviour
CI/CD pipeline failures
Performance regressions
Especially when:
Under time pressure (emergencies make guessing tempting)
"Just one quick fix" seems obvious
You've already tried multiple fixes that didn't work
You don't fully understand the issue
Don't skip when:
Issue seems simple (simple bugs have root causes too)
You're in a hurry (rushing guarantees rework)
Manager wants it fixed NOW (systematic is faster than thrashing)
The Four Phases
Complete each phase before proceeding to the next.
Phase 1: Root Cause Investigation
Before attempting ANY fix:
1. Read Error Messages Carefully
Don't skip past errors or warnings โ they often contain the exact solution
For FastAPI: read the full Pydantic validation error body, not just "422 Unprocessable Entity"
For vitest: read the diff between expected and received, not just "FAIL"
For TypeScript: read the full type error chain, not just the last line
2. Reproduce Consistently
Can you trigger the failure reliably?
What are the exact steps / the exact test command?
Does it happen every time, or intermittently?
If not reproducible โ gather more data. Do not guess.
3. Check Recent Changes
git diff HEAD~1 # What changed since last green state
git log --oneline -10 # Recent commit context
git stash && pnpm turbo run test# Does it fail on main without your changes?
4. Gather Evidence in Multi-Component Systems
When the stack has multiple layers (frontend โ API โ backend โ database), add instrumentation at each boundary before proposing fixes:
# FastAPI route โ log incoming requestprint(f"=== Request body: {request_data.model_dump()}")
# Service layer โ log what reached itprint(f"=== Service input: {params}")
# Database query โ log the generated SQLprint(f"=== SQL: {str(stmt.compile(compile_kwargs={'literal_binds': True}))}")
// Next.js API routeconsole.log('=== Fetch params:', { url, method, body })
// React componentconsole.log('=== Props received:', props)
console.log('=== State:', stateValue)
Run once to gather evidence. THEN analyse which layer is failing. THEN investigate that specific layer.
5. Trace Data Flow
Where does the bad value originate?
What called this function with the bad value?
Keep tracing up the call stack until you find the source
If implementing a known pattern, read the reference implementation completely. Do not skim โ read every line. Understand the pattern fully before applying.
3. Identify Differences
List every difference between the working example and the broken code โ however small. Don't assume "that can't matter."
4. Understand Dependencies
What environment variables, config, external services, or Docker containers does this depend on?
# Check env vars are presentcat .env | grep RELEVANT_KEY
# Check Docker services are running
pnpm run docker:up
docker ps
Phase 3: Hypothesis and Testing
1. Form a Single, Specific Hypothesis
State clearly: "I think X is the root cause because Y."
Write it down. Be specific โ not "something is wrong with auth" but "the JWT secret is not being passed to the validation middleware because the env var name changed."
2. Test Minimally
Make the smallest possible change to test the hypothesis. ONE variable at a time. Do not fix multiple things at once.
3. Verify Before Continuing
Fix worked? YES โ Phase 4
Didn't work? Form a new hypothesis. Do NOT add more fixes on top of the failed one.
4. When You Don't Know
Say "I don't understand X." Do not pretend to know. Research more, read the docs, or ask.
Phase 4: Implementation
1. Write a Failing Test First
Use the tdd skill. Write the minimal test reproducing the bug before writing the fix.
# Frontend โ write test, confirm it fails
pnpm test --filter=web
# Backend โ write test, confirm it failscd apps/backend && uv run pytest tests/unit/test_specific.py -v
2. Implement a Single Fix
Address the root cause identified in Phase 1. ONE change at a time. No "while I'm here" refactoring.
3. Verify the Fix
# Run full test suite to confirm no regressions
pnpm turbo run test
4. Circuit Breaker โ If Fix Doesn't Work
Fix Attempt
Action
1 failed
Return to Phase 1 with new information
2 failed
Return to Phase 1. Add more instrumentation.
3 failed
STOP. Invoke Step 5 โ question the architecture
Never attempt Fix #4 without an architectural discussion first.
5. 3+ Fixes Failed โ Question the Architecture
Pattern indicating an architectural problem:
Each fix reveals new coupling or shared state in a different place
Fixes require "massive refactoring" to implement correctly
Each fix creates new symptoms elsewhere
STOP and question fundamentals:
Is this design pattern fundamentally sound?
Are we "sticking with it through sheer inertia"?
Should we refactor the architecture rather than continue fixing symptoms?
Discuss with your human partner before attempting more fixes. This is not a failed hypothesis โ this is a wrong architecture.
Red Flags โ STOP and Return to Phase 1
If you catch yourself thinking:
"Quick fix for now, investigate later"
"Just try changing X and see if it works"
"It's probably X, let me fix that"
"I don't fully understand but this might work"
"Here are the main problems:" [lists fixes without investigation]
Proposing solutions before tracing data flow
"One more fix attempt" (when already tried 2+)
Each fix reveals new problem in a different place
ALL of these mean: STOP. Return to Phase 1.
If 3+ fixes failed: Question the architecture (Phase 4, Step 5).
Common Rationalisation โ Reality
Rationalisation
Reality
"Issue is simple, don't need process"
Simple issues have root causes too. The process is fast for simple bugs.
"Emergency, no time for process"
Systematic debugging is faster than guess-and-check thrashing.
"I'll write the test after confirming the fix"
Untested fixes don't stick. Test first proves the fix.
