| name | debugging-methodology |
| version | 1.0.0 |
| description | Structured debugging workflow — hypothesis-driven, evidence-based, reproducible. Produces auditable findings, not just a fix. |
| tags | ["debugging","troubleshooting","methodology","engineering","incident"] |
| tool_agnostic | true |
Debugging Methodology
A structured, hypothesis-driven approach to debugging. The goal is not just to fix the immediate issue — it is to understand what actually happened and why, so the fix is correct and the knowledge is retained.
Use When
- A bug is not immediately obvious from reading the code
- A system behaves differently than expected in ways that are hard to reproduce
- An incident needs a documented root cause, not just a patch
- A debugging session has been running in circles and needs a reset
Do Not Use When
- The fix is obvious and the risk is low — just fix it
- The task is exploratory prototyping, not debugging a specific failure
Core Principle
Never guess twice. Form a hypothesis, test it with the minimum action needed to confirm or deny it, then update your understanding. A bug fixed by trial and error is a bug that will return.
Procedure
Phase 1 — Establish the Baseline
-
State the symptom precisely. What is the observed behavior? What is the expected behavior? Where and when does it occur?
-
Make it reproducible. If you cannot reproduce the bug reliably, you cannot confirm you have fixed it. Invest in a minimal reproduction case.
-
Gather evidence before touching anything. Logs, stack traces, error messages, network traffic, database state, environment configuration. Capture the state before any changes.
-
Define the blast radius. What is affected? What is confirmed not affected? This scopes the investigation.
Phase 2 — Form Hypotheses
-
List 2-3 candidate hypotheses. Each should be a falsifiable claim about the cause. "The database is slow" is not a hypothesis. "The N+1 query in OrderService.getItems() is causing timeouts under load" is.
-
Order by likelihood and testability. Test the most likely and easiest-to-test hypothesis first.
-
State what evidence would confirm or deny each hypothesis. Know what you are looking for before you look.
Phase 3 — Test Systematically
-
Change one thing at a time. Multiple simultaneous changes make it impossible to know what fixed the problem.
-
Test the hypothesis, not the fix. Confirm the cause before applying the solution.
-
Document what you tried and what it showed. If you hand off the investigation or need to revisit it, this log is essential.
Phase 4 — Fix and Verify
-
Apply the fix once the cause is confirmed. The fix should follow directly from the confirmed hypothesis.
-
Verify the fix against the original reproduction case. Confirm the symptom is gone.
-
Check for regressions. Run the relevant test suite. Check adjacent behavior.
-
Confirm the fix under conditions close to production. A fix that works locally but not under load or in a specific environment is not a fix.
Phase 5 — Document and Close
-
Write a brief root cause summary. What was the actual cause? What masked it? Why did it occur?
-
Note any systemic issues the bug exposed. Missing test coverage, unclear ownership, configuration drift, absent monitoring.
-
State what would catch this class of bug earlier. A test, a log line, an alert, a linting rule.
Output Shape
For anything non-trivial, produce a brief debugging record:
- Symptom — observed vs. expected behavior
- Reproduction case — minimum steps to trigger
- Hypotheses tested — what was tried and what each test showed
- Root cause — confirmed cause in plain terms
- Fix applied — what was changed and why
- Verification — how the fix was confirmed
- Follow-up items — systemic issues, missing coverage, monitoring gaps
Common Mistakes To Avoid
- Starting with a fix before understanding the cause
- Changing multiple things simultaneously
- Closing a bug when the symptom disappears without confirming the root cause
- Ignoring evidence that contradicts the favored hypothesis
- Treating a workaround as a fix
- Not checking whether the bug can recur under different conditions
