dev-debugging — Systematic Root Cause Analysis

Boundary: This skill covers how to reason about bugs. For test harness, reproduction frameworks, and verification tooling, see dev-testing. For domain-specific context (API errors, hydration issues, query performance), consult dev-backend or dev-frontend. Comprehension without a defect — understanding how an unknown app, API, AI tool, or codebase works — routes to references/logic-analysis.md.

Class, fast path, rule authority, proof, and safety: dev. Current/public evidence: dev routing.

Core Principle

Check if the problem is structural before debugging code. Before a permanent fix, investigate and explain the cause. During an active incident, an already-authorized, reversible mitigation may precede full RCA; follow dev-devops incident policy and preserve evidence. Diagnosis alone never authorizes a code fix, rollback, production access, or an upstream issue submission.

RCA Entry Gates

STRICT (DEBUG-RCA-EVIDENCE-01): Before investigating any single root-cause hypothesis or making a root-cause claim, write at least three orthogonal hypotheses (H1/H2/H3) and one falsifier for each. Collapse duplicates, test against disconfirming evidence, and do not claim root cause until competing hypotheses have been ruled out by evidence. If fewer than three are plausible, state why.

STRICT (DEBUG-TOGGLE-PROOF-01): Enter implementation only after the captured value matches the hypothesis prediction, the repro repeats, and toggling the suspected cause off/on removes then restores the bug. Write one paragraph explaining the causal mechanism before patching.

Logic Analysis (comprehension without a defect)

When the request is to understand how a system works — closed app, AI tool, undocumented API, unfamiliar codebase — rather than to fix a defect, read Logic analysis. Core rules: "I can't" is a skipped analysis loop, not a limit; missing source/docs is a starting condition; hypothesize from names/strings/errors, observe static AND dynamic, mutate one variable at a time, keep an incremental model with UNKNOWN fields, and prove the model by writing a client that uses it. Honest lab-boundary routing (IDA/Procmon/Cuckoo class) beats both refusal and fabrication.

Security-Sensitive Bugs

For security-sensitive bugs (auth bypass, data leak, injection), use dev-security for controls and dev-devops for incident response. Preserve the same authorization boundary.

Modular References

Condition	Reference
Defect diagnosis before permanent repair: phases 0–4 and implementation entry gates	root-cause-phases.md
Guessing, repeated failures, or suppressive fixes	debugging-pitfalls.md
API 500, hydration mismatch, N+1 query, or flaky-test diagnosis examples	debugging-scenarios.md
Investigation stalls, needs escalation, or meets postmortem criteria	escalation-and-postmortems.md
Choosing the boundary between debugging and companion skills	skill-boundaries.md
Choosing a debug approach	methodologies.md
Understanding how an unknown system works (no defect)	logic-analysis.md
Concurrency issues	async-debugging.md
Quick cheatsheet	tool-guides.md
After resolving a significant incident	postmortem-template.md
Node.js / tsx / Bun / Deno	runtimes/node.md
Next.js 16 / React 19	runtimes/js/nextjs-react.md
Vite 8 / Vitest 4	runtimes/js/vite-vitest.md
Express 5 / Fastify 5 / NestJS 11	runtimes/js/node-backend.md
Python (CPython 3.9+)	runtimes/python.md
Rust	runtimes/rust.md
Go	runtimes/go.md
C/C++	runtimes/c-cpp.md
Java/Kotlin (JVM)	runtimes/jvm.md
Swift / iOS / macOS AppKit	runtimes/swift.md
Ruby (3.2+)	runtimes/ruby.md
Elixir/Erlang (BEAM)	runtimes/beam.md
Browser/web-surface bugs	tools/playwright.md