The Bug Fix Cycle

In one line: Investigate root cause, then write a failing test that reproduces the bug before touching the fix.

Do this: No fix lands without a test that fails before it and passes after — that test proves the hypothesis and prevents regression.

The bug fix cycle is a compressed lifecycle for defect resolution. It differs from the full cycle in two ways: it starts with investigation rather than brainstorming, and it requires a failing test before any code changes.

The Systematic Debugging skill (/systematic-debugging) enforces a four-phase investigation process:

Phase 1: Root Cause Investigation. Gather evidence before hypotheses — read the failing code, the test, the error, the logs; trace data flow from input to failure point. The skill prohibits "guess-and-check" debugging, which masks root causes rather than resolving them.

Phase 2: Pattern Analysis. Categorize the failure: data (wrong/missing value, type mismatch), flow (wrong path, missing transition), timing (race, async ordering), or integration (contract mismatch, schema drift). The category determines where to look and what fix is appropriate.

Phase 3: Hypothesis Testing. Form a specific, testable hypothesis ("X receives null when upstream Y passes an empty result set"). Verify with logging, a breakpoint, or a targeted test. If wrong, return to Phase 1 with the new evidence.

Phase 4: Implementation. With the root cause confirmed, write a failing test that reproduces the exact mode, then implement the minimal fix — the smallest change that passes it without new behavior. Verify no regressions.

The mandatory failing test is the critical gate. It serves two purposes: it proves the root cause hypothesis is correct (the test reproduces the bug), and it prevents regression (the test will catch this bug if it is reintroduced). A bug fix without a failing test is a fix without proof.

---