systematic-debugging

Systematic Debugging

Iron Rules

근본 원인 파악 없이 수정 시도 절대 금지

4-Phase Process

Phase 1: Root Cause Investigation

Before attempting any fix, you must:

1. Read the error message carefully — read the entire stack trace, note line numbers/file paths
2. Reproduce — Can it be triggered consistently? What are the exact steps?
3. Check recent changes — git diff, recent commits, new dependencies, config changes
4. Trace the data flow — Where does the bad value originate? Trace backward

For multi-component systems: Add diagnostic logs at each boundary → run once → see where it breaks → investigate only that component

Phase 2: Pattern Analysis

1. Find a working example — similar working code in the same codebase
2. Compare with the reference — read the reference documentation completely when implementing a pattern (no skimming!)
3. Identify the differences — list every difference between working/non-working
4. Identify dependencies — other required components, config, environment

Phase 3: Hypothesis Testing

1. Form a single hypothesis — "X is the root cause. Because Y"
2. Test with the minimal change — change only one thing at a time
3. Verify — if it works, go to Phase 4; otherwise, form a new hypothesis
4. If you don't know, admit you don't know — do not guess

Phase 4: Implementation

1. Write a failing test case — before the fix, first
2. Implement a single fix — address only the root cause, no "while I'm at it" improvements
3. Verify — Do the tests pass? Are no other tests broken?
4. If 3 or more fix attempts fail → suspect the architecture
   • Does each fix reveal a new problem?
   • If a "large-scale refactor" is needed?
   • STOP — the fundamental design is wrong. Discuss with the Master.

🚨 Red Flags — stop immediately and go to Phase 1

• "Let's just try changing X and see if it works"
• "Test multiple changes all at once"
• "Quick fix, investigate later"
• "I think this is roughly the problem"
• "I checked it manually, so it should work"
• Proposing a fix without investigation
• 2 or more fix attempts fail

Preventing Rationalization

Excuse	Reality
"It's a simple problem, so no process is needed"	Even simple bugs have a root cause
"I'm in a hurry and don't have time to follow the process"	Systematic debugging is faster than guessing
"Let's just try this first"	The first fix determines the pattern
"The reference documentation is too long"	Partial understanding = guaranteed bugs