The systematic-debugging Skill — Root Cause Before Any Fix

The fastest way to spend three hours on a one-hour bug is to start fixing before understanding. The systematic-debugging skill exists to prevent that. Its iron law: no fix is permitted until the root cause has been identified.

This applies in every situation the skill lists — test failures, production bugs, build errors, performance problems, integration issues. The rule does not relax under time pressure. The skill notes explicitly that systematic investigation is faster than guessing under pressure, not slower.

Four phases

The skill organizes work into four sequential phases, each of which must complete before the next begins.

Phase 1 is root cause investigation. Read the error message completely — stack traces, line numbers, error codes. Reproduce the issue consistently. Check what changed recently. When the system has multiple components, add diagnostic instrumentation at every component boundary before proposing anything: log what enters, log what exits, verify configuration propagates. One run gathers the evidence; analysis follows.

Phase 2 is pattern analysis. Find working code in the same codebase that resembles the broken piece. Compare the two side by side and list every difference, however small. Understand what the working version depends on that the broken one does not.

Phase 3 is hypothesis and testing. State one specific hypothesis — "I think X is the root cause because Y" — and make the smallest possible change to test it. One variable at a time. If the change does not confirm the hypothesis, form a new one. No stacking of fixes.

Phase 4 is implementation. Create a failing test case first, address the identified root cause with one change, then verify. If three separate fixes have failed to resolve the issue, the skill mandates stopping and questioning the architecture rather than attempting fix number four.

The 3-fix limit

The three-fix limit is one of the skill's most concrete rules. When each attempted fix reveals a new problem in a different place, or every fix requires large-scale refactoring, that pattern indicates an architectural problem — not a missed detail. At that point the right action is to discuss the architecture, not to keep patching.

Red flags

The skill lists specific phrases and impulses that signal a violation of the process: "quick fix for now, investigate later," "add multiple changes and run tests," "I don't fully understand but this might work." Each one is a prompt to stop and return to Phase 1. The skill's reported outcome data — 15–30 minutes with systematic debugging versus 2–3 hours with random fixes, 95% first-time fix rate versus 40% — reflects what happens when these red flags are ignored versus respected.

The systematic-debugging skill pairs naturally with the testing skill (creating the failing test case in Phase 4) and with utilities for shell-based diagnostic instrumentation. For the broader Datarim picture, see what is Datarim.