diagnose

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:

1. What is the exact failing condition?
2. Why does it fail — what is the underlying cause?
3. 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:

1. Read the full error — stack trace, error message, file, line number
2. Reproduce it in isolation (minimal test case if possible)
3. Identify the last known good state
4. Ask: "What changed between working and broken?"
5. Follow the data — trace the actual value, not the expected value, through the call chain
6. 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