debugging

Debugging

Overview

Purpose: Replace guesswork with evidence-based diagnosis. Most "quick fixes" fail because they address symptoms, not causes. This skill enforces understanding before action.

Core principle: A bug you cannot explain is a bug you have not fixed, even if the symptoms disappear. "Just one quick fix" is how bugs hide behind other bugs.

Announce at start: "I'm using debugging — I'll diagnose the root cause before proposing any fix."

When to use

• Bug reports (user-reported, CI failures, production incidents)
• Behavior that contradicts documentation or specs
• Flaky tests or intermittent failures
• Performance regressions
• "It works on my machine" scenarios

When NOT to use

• The cause is already known and documented (just fix it)
• Typos, obvious syntax errors, missing imports (just fix it)
• Feature requests disguised as bug reports (use brainstorming)

Trigger examples

• "CI is broken. Find out why."
• "This endpoint sometimes returns 500 and we do not know why."

Workflow

Phase 0: Branch guard (mandatory)

Before doing anything, check the current git branch. If on a baseline branch (main, master, test), create a working branch first:

git checkout -b fix/<slug-from-bug-description>

Do NOT debug and fix on a baseline branch. Even investigation notes and regression tests belong on a working branch.

Phase 1: Understand (do NOT write fixes yet)

Step 0: Load deep context

Dispatch context-loader with the bug description. The pack should surface relevant runbooks, ADRs, and architecture sections before you start reproducing.

Step 1: Reproduce

• Make it fail on demand. A bug you cannot reproduce is a bug you cannot verify as fixed.
• Define the exact inputs, environment, and sequence of steps
• If intermittent: identify the conditions that increase failure probability (concurrency, timing, specific data)
• Write down the reproduction steps explicitly — you will need them later for the regression test

If you cannot reproduce: Gather more evidence (logs, traces, user screenshots). Do not guess. Ask the reporter for exact steps.

Step 2: Isolate

Narrow the scope systematically:

Technique	When to use
Binary search (bisect)	"It used to work" — find the breaking commit
Input reduction	Complex input triggers bug — find minimal failing input
Component isolation	Remove layers until the bug disappears, then re-add the last one
Environment comparison	Works in one env, fails in another — diff the environments
Log tracing	Add targeted logging to trace execution path through the failure

Do not:

• Change multiple things at once
• Skip straight to the code you "suspect" — suspicion is not evidence
• Assume the bug is in your code — it could be in dependencies, config, or infrastructure

Step 3: Gather evidence

Collect and document:

• Error messages and stack traces (full, not truncated)
• Relevant log output around the failure timestamp
• State of the system at failure time (database contents, cache state, env vars)
• What the code actually does vs. what it should do (trace the execution path)

Step 4: Document root cause

Before proposing any fix, write a clear explanation:

1. What happens: Concrete description of the failure
2. Why it happens: The mechanism — not "the code is wrong" but "the query returns null when the user has no profile, and the serializer calls .name on null"
3. When it happens: The specific conditions that trigger the failure
4. Since when: When was this introduced (commit, release, config change)

If you cannot fill in all four, you do not understand the bug well enough to fix it.

Phase 2: Fix (only after Phase 1 is complete)

Step 5: Write a regression test

• Write a test that reproduces the bug and currently fails (RED)
• This test captures your understanding of the root cause
• It will prevent this exact bug from recurring
• Follow test-driven-development discipline

Step 6: Evaluate the fix

Before writing the fix, consider:

• Will this fix introduce new bugs? Trace the impact of your change through related code paths
• Is this the right layer to fix? A null check in the serializer might mask a deeper issue in the query
• Are there similar bugs elsewhere? If the pattern that caused this bug exists in other places, flag them (fix or track as separate issues)

Step 7: Implement the minimal fix

• Fix the root cause, not the symptom
• Make the smallest change that addresses the actual problem
• Run the regression test — it should now pass (GREEN)
• Run the full test suite — nothing else should break

Step 8: Verify

• Reproduce the original scenario — confirm it now works
• Test related scenarios that share code paths
• If the bug was in production, verify in an environment that matches production

Rules

1. No fix before diagnosis. Phase 1 must be complete before Phase 2 begins.
2. Every fix gets a regression test. No exceptions. If you cannot test the fix, you cannot prove the fix works.
3. Document the root cause in the commit message. Future developers need to understand why the change was made, not just what changed.
4. One bug, one fix, one commit. Do not bundle unrelated fixes. Do not "clean up while you're in there" in the same commit.
5. If the fix is larger than expected, pause. A "simple bug fix" that turns into a refactor needs a plan. Switch to writing-plans if necessary.

Common root cause categories

Category	Symptoms	Investigation approach
State management	Intermittent, order-dependent	Check shared mutable state, race conditions
Boundary conditions	Fails on specific inputs	Test edges: empty, null, zero, max, negative
Environment	Works locally, fails elsewhere	Diff configs, versions, env vars
Timing	Intermittent, load-dependent	Check async operations, timeouts, connection pools
Data integrity	Fails for specific records	Inspect the actual data; check migrations, seeds
Dependency changes	Fails after update	Check changelogs, breaking changes, version pins

Anti-patterns

• "I think I know what's wrong" — Hypotheses are fine. Skipping investigation because of a hypothesis is not. Confirm before you fix.
• Changing code to see what happens — This is not debugging; it is gambling. Understand first.
• Fixing the test instead of the code — If a test fails, ask why. If the test expectation is wrong, fix the test. If the code is wrong, fix the code. Do not adjust one to match the other without understanding which is correct.
• The shotgun fix — Adding null checks, try-catch blocks, and default values everywhere near the failure point. One of them might suppress the symptom. None of them address the cause.
• "It works now" — If you do not know why it failed, you do not know why it works. It will fail again.

Integration

Pairs with:

• skills/test-driven-development — regression test follows TDD flow
• skills/verification-before-completion — verify the fix before claiming done
• skills/compound-retrospective — document lessons if the bug reveals systemic issues