debugger

name	debugger
description	Systematically diagnoses and resolves software defects using a structured, scientific approach. Applies isolation, binary chop, and root cause analysis techniques. Use when investigating bugs, diagnosing errors, tracing unexpected behavior, or resolving test failures.

Scientific Debugging

Protocol

Follow these 4 steps for every defect. Do not skip steps or take shortcuts.

1. Isolate: Write a failing test first

Before modifying any production code, write a failing test that reproduces the defect. This:

• Proves you understand the exact conditions that trigger the bug
• Creates a regression baseline
• Gives you a clear signal when the fix works

2. Diagnose: Understand before changing

• Read the surrounding code before touching anything. Resist the urge to tweak and see what happens.
• Apply the scientific method: Gather data, form a hypothesis, test it. Ensure your hypothesis explains all observed behaviors, not just a subset.
• Binary chop: For obscure bugs, use divide-and-conquer to narrow the search space. Bisect commit history, comment out code blocks, or reduce input data until you isolate the trigger.
• Check the usual suspects: Recently modified code, historically problematic modules, environment differences, race conditions.

3. Fix: Cure the root cause

• Fix the underlying cause, not the symptom. No band-aid patches, no exception masking, no workarounds.
• Make exactly one small, controlled, atomic change. If it doesn't work, revert immediately.
• Preserve existing code structure. Do not use the fix as an excuse to refactor.

4. Verify and learn

• Confirm the test from Step 1 now passes.
• Run the full relevant test suite to check for regressions.
• Provide a brief 5 Whys analysis: Why did this bug exist? What allowed it to reach production? How can similar bugs be prevented?

Diagnostic tools

• Logs and traces: For timing, concurrency, and distributed system issues.
• git bisect: To find the exact commit that introduced a regression.
• Strategic debug output: Add temporary logging at key decision points, remove it after diagnosis.

Constraints

• Never refactor during debugging. The goal is a minimal, surgical fix.
• No change-marker comments. Leave no // fix applied breadcrumbs.
• If the root cause is architectural, report it and propose a fix separately. Do not combine debugging with redesign.