Debugging Systematic

Systematic Debugging Methodology

Core Principle

Debugging is not guessing. It is a scientific process: observe the symptom, form a hypothesis, predict the outcome of a test, and run the test. Repeat until the root cause is found.

---

The Scientific Debugging Method

Step 1: OBSERVE — Gather Evidence

Before changing anything, collect all available information.

Checklist:

• [ ] Read the FULL error message, not just the first line.
• [ ] Read the FULL stack trace. Identify the frame in YOUR code (skip framework internals).
• [ ] Note the exact input / request / action that triggered the bug.
• [ ] Note the expected behavior vs. the actual behavior.
• [ ] Check logs (application logs, server logs, browser console).
• [ ] Note the environment (OS, runtime version, dependency versions, config).
• [ ] Check if the bug is reproducible. If not, note the frequency and conditions.

Key question: Can I reproduce this bug reliably? If not, gathering more observations is the priority.

Step 2: HYPOTHESIZE — Form a Theory

Based on the evidence, propose a specific, falsifiable explanation.

Good hypothesis format: > "The crash occurs because user.profile is null when the user has not completed onboarding, and line 47 accesses user.profile.name without a null check."

Bad hypothesis: > "Something is wrong with the user object."

Rules:

• The hypothesis must explain ALL observed symptoms.
• If it only explains some symptoms, it is incomplete — keep refining.
• Generate multiple competing hypotheses and rank by likelihood.

Step 3: PREDICT — Design an Experiment

Before touching the code, predict what you will see IF your hypothesis is correct.

Examples:

• "If the null profile hypothesis is correct, then logging user.profile on line 45 will print null for users created after January 1."
• "If the race condition hypothesis is correct, then adding a 500ms delay before the second call will make the bug disappear."

Step 4: TEST — Run the Experiment

Execute one change at a time. Observe whether the prediction matches.

Rules:

• Change ONE thing at a time. Multiple changes make it impossible to attribute cause.
• Revert experiments that did not help. Do not accumulate random changes.
• Use version control: commit or stash working state before experimenting.

Step 5: CONCLUDE

• If the prediction matched, you have likely found the cause. Write a fix and a regression test.
• If the prediction did not match, your hypothesis was wrong. Return to Step 2 with new information.

---

Binary Search Isolation

When you have no idea where the bug lives, use binary search to narrow it down.

In Code

1. Identify the entry point and the crash / wrong output point.
2. Add a log or assertion at the MIDPOINT of the code path.
3. Is the state correct at the midpoint?

• YES -> The bug is in the second half. Move your probe to the 75% point.
• NO -> The bug is in the first half. Move your probe to the 25% point.

1. Repeat until you have isolated the exact line or function.

In Time (git bisect)

git bisect start
git bisect bad              # Current commit is broken
git bisect good     # This commit was known to work
# Git checks out the midpoint. Test it.
git bisect good  # or  git bisect bad
# Repeat until git identifies the first bad commit.
git bisect reset

In Data

1. Take the failing input dataset.
2. Remove half the data.
3. Does the bug still occur?

• YES -> The bug is in the remaining half, or is independent of the removed data.
• NO -> The trigger is in the removed half. Restore it and remove the other half.

1. Repeat until you find the minimum failing input.

---

Reading Stack Traces

Anatomy of a Stack Trace

Error: Cannot read properties of null (reading 'name')      Detailed variable dumps (temporary, remove after fixing)
INFO   -> Flow markers ("entered function X", "querying database")
WARN   -> Unexpected but handled conditions ("retrying after timeout")
ERROR  -> Unhandled exceptions and failures

Temporary Debug Logging Pattern

# Add a unique tag so you can find and remove all debug logs later
print("[DEBUG-ISSUE-123] user_id:", user_id, "profile:", profile)

When done, search for [DEBUG-ISSUE-123] and remove all instances.

---

Common Bug Categories

1. Off-by-One Errors

• Symptoms: Missing first/last element; array index out of bounds; fence-post errors.
• Check: Loop bounds (` It is in the uncommented half.
• NO -> It is in the commented half.

1. Repeat until isolated.

---

Key Principles

1. Reproduce first. If you cannot reproduce it, you cannot verify your fix.
2. One change at a time. Multiple changes destroy your ability to reason about cause and effect.
3. Read before you write. Spend more time reading code and logs than writing fixes.
4. Trust nothing. Verify your assumptions. Print the value. Check the type. Read the documentation.
5. The bug is in your code. It is almost never the compiler, the OS, or the framework. Check your code first.
6. Write the regression test. A bug without a test is a bug that will return.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Claude-Code-Community-Ireland
• Source: Claude-Code-Community-Ireland/claude-code-resources
• License: MIT

Install and usage instructions live in the source repository linked above.