Debugging & System Investigation

Output style: Follow process/development-protocols/communication-standards.md, answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Comprehensive framework combining systematic debugging, root cause tracing, defense-in-depth validation, verification protocols, and system-level investigation (logs, CI/CD, databases, performance).

Core Principle

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

Random fixes waste time and create new bugs. Find root cause, fix at source, validate at every layer, verify before claiming success.

When to Use

Code-level: Test failures, bugs, unexpected behavior, build failures, integration problems System-level: Server errors, CI/CD pipeline failures, performance degradation, database issues, log analysis Always: Before claiming work complete

Techniques

1. Systematic Debugging (references/systematic-debugging.md)

Four-phase framework: Root Cause Investigation → Pattern Analysis → Hypothesis Testing → Implementation. Complete each phase before proceeding. No fixes without Phase 1.

Load when: Any bug/issue requiring investigation and fix

2. Root Cause Tracing (references/root-cause-tracing.md)

Trace bugs backward through call stack to find original trigger. Fix at source, not symptom. Includes scripts/find-polluter.sh for bisecting test pollution.

Load when: Error deep in call stack, unclear where invalid data originated

3. Defense-in-Depth (references/defense-in-depth.md)

Validate at every layer: Entry validation → Business logic → Environment guards → Debug instrumentation

Load when: After finding root cause, need comprehensive validation

4. Verification (references/verification.md)

Iron law: NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE. Run command. Read output. Then claim result.

Load when: About to claim work complete, fixed, or passing