| name | diagnose |
| description | 4-phase debugging methodology — Root Cause Investigation, Pattern Analysis, Hypothesis Testing, and Implementation. Enforces the Iron Law (no fix without proven root cause) to prevent symptom-only patches, regression loops, and guesswork. Use when diagnosing bugs, reviewing a failed test, or responding to an error before writing any fix. Adapted from obra/superpowers (MIT). |
| license | MIT |
| compatibility | Portable reference skill for agents that support markdown skills or prompt files. Works best alongside project source files and test output. |
| disable-model-invocation | true |
| metadata | {"owner":"game-delivery","version":"2.0.0","language":"en-GB","category":"pipeline","upstream_references":["https://github.com/obra/superpowers (Iron Law debugging methodology, MIT — see NOTICE.md)"],"tags":["debugging","root-cause","methodology","systematic","engineering-process"],"intents":["root-cause-investigation","pattern-analysis","hypothesis-testing","regression-guard","intermittent-bug-triage"],"output_types":["root-cause-analysis","hypothesis-test","fix-recommendation","regression-risk","repro-case"]} |
Systematic Debugging
The Iron Law
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.
Before writing a single line of fix code, you must be able to answer:
- What is the exact failing condition?
- Why does it fail — what is the underlying cause?
- How does the proposed fix address that cause (not just the symptom)?
If you cannot answer all three, you are not ready to fix. Continue investigating.
The 4 Phases
Phase 1 — Root Cause Investigation
Reproduce the failure precisely, then trace it to its source.
Steps:
- Read the full error — stack trace, error message, file, line number
- Reproduce it in isolation (minimal test case if possible)
- Identify the last known good state
- Ask: "What changed between working and broken?"
- Follow the data — trace the actual value, not the expected value, through the call chain
- Do not stop at the first plausible cause; keep asking "why?"
Questions to ask:
- What input causes the failure?
- What is the exact error vs what was expected?
- Does it fail consistently or intermittently?
- Is it environment-specific (dev/prod, OS, browser, hardware)?
- What was the last commit that didn't have this bug?
Tools:
// Browser
console.log / console.table / debugger
DevTools breakpoints, call stack, scope inspection
Performance tab for rendering issues
// Node / server
node --inspect // Attach debugger
DEBUG=* node server.js // Verbose logging
// Three.js / WebGL
renderer.info // Draw calls, triangles, textures in VRAM
Spector.js // WebGL call capture per frame
Phase 2 — Pattern Analysis
Understand what class of problem this is before attempting a fix.
Identify the pattern:
- Off-by-one / boundary error — range, array index, loop termination
- Race condition / async ordering — timing-dependent, intermittent
- State mutation — shared mutable state, unexpected side-effects
- Missing guard / null check — undefined path through logic
- Type mismatch — wrong data type arriving at a function
- Resource lifecycle — use-after-free, missing disposal, double-init
- Configuration error — wrong env var, wrong import path, wrong default
