pjc-systematic-debugging

Follow a four-phase process: read the full error and stack trace, reproduce reliably with a feedback loop, form multiple falsifiable hypotheses, and verify each with minimal probes. Only implement a fix after the root cause is confirmed by evidence.

Write a failing test that reproduces the bug first (RED), then apply the minimal fix until it passes (GREEN). If the bug is a compile failure where RED is impossible, fix compilation first and use the passing build as the initial verification.

A lightweight path applies only when the compiler or stack trace explicitly pinpoints the file, line, and cause, and the fix is a small single-file change. If multi-file impact emerges or the initial diagnosis proves wrong, escalate back to the full process.

Test hypotheses about environment differences (OS, runtime version, timezone, locale, permissions), timing dependencies (races, first-run), data dependencies, and external system states. If reproduction stays impossible and no hypothesis verifies, halt and report to the user.

Recurrence after three or more fixes, or fixes breaking other areas, signals an architecture problem rather than a failed hypothesis. Stop patching symptoms and report the architectural suspicion to decide on refactoring together.