Debug

<skill id="debug">

<purpose>
Debugging is forming and testing a THEORY that explains the bug.
Not random changes. Not guessing. Scientific method applied to code.
DEFECT (in code) → INFECTION (in state) → FAILURE (visible symptom).
The failure you see is NOT where the bug is. Binary search upstream.
Systematic methodology beats ad-hoc guessing. The process is the multiplier.

Diagnosis comes before prescription: a surgeon cutting before the X-ray is guessing with a knife. Two modes, same discipline. bug (default) is the steps below. refactor swaps the subject from a failure to a structure, and produces a plan instead of a fix. </purpose>

<prerequisite>Run agentdb recall with the exact error text, subsystem/library, failing test, and known files/symbols. Recall again when the hypothesis changes or a new failure appears; that is a new retrieval question. Reference on demand: skills/debug/reference/debug-research.md.</prerequisite>

<steps>
1. **REPRODUCE**: get specific before touching code.
   - Document: exact input, expected output, actual output (full stack trace), environment, frequency.
   - "Sometimes fails" is not a reproduction. Get deterministic.
   - Sensitive or high-blast-radius bug: investigate read-only (plan mode) and settle the approach before any edit.
   <!-- Updated 2026-09-20: sitepoint.com / claudelog.com Claude Code debugging guides -->
   - (gate: can reproduce consistently, OR have added targeted logging to wait for next occurrence)

2. HYPOTHESIZE: list 3 causes before pursuing any.

   • Read ALL error output first (anchoring bias mitigation).
   • Write each hypothesis to AgentDB. Prevents circular re-investigation.
   • (gate: 3 candidate hypotheses written; none pursued yet)

3. ISOLATE: binary search, O(log n) not O(n).

   • Code: call chain A→B→C→D→E fails → check midpoint C → recurse into failing half.
   • Time: git bisect between known-good and known-bad commit. ~10 tests for 1000 commits.
   • Input: large failing input → split in half → recurse to minimal reproduction case.
   • Instrument at boundaries: log inputs/outputs at each layer boundary.
   • Mock external dependencies to isolate which one causes failure.

   <!-- Updated 2026-09-19: dev.to flaky-test patterns; claudelog/sfeir debugging guides -->

   • Diff working vs failing state (env, config, input, commit) before theorizing.

   • Flaky test: classify first as timing/race, shared state, unseeded randomness, or environment difference; only then propose a fix.

   • (gate: failure localized to a specific function/commit/input subset)

4. ROOT CAUSE: the error line is the FAILURE. The DEFECT is upstream.

   • Ask: what assumption was violated? What invariant broke?
   • If you can't explain WHY it broke, you haven't found root cause.
   • Top causes by frequency: wrong input shape/type · off-by-one · missing null check · race condition · shared-state mutation · wrong comparison operator · variable scope · swallowed error · API contract mismatch · environment difference.
   • (gate: can state root cause in one sentence explaining the violated invariant)

5. FIX: root cause, not symptom.

   • Fix the DEFECT, not the FAILURE site. (Null check at crash site = symptom fix.)
   • Write regression test that fails before fix, passes after.
   • Run: original failing case + edge cases + full regression suite.
   • Commit fix + test together.
   • (gate: regression test green; original failing case passes)

     </steps>

<refactor_mode> Triggers: refactor, restructure, clean up, coupling, dependency, "what breaks if". Same rule: diagnose, then hand off. Do not start cutting inside this mode.

1. MAP: every file/module touching the target. Grep/Glob every reference, or graphify affected <symbol> when the graph is fresh. Build the import/call map.
2. TRACE DEPS: per file, who calls it, who depends on it, what breaks if it changes.
3. MEASURE COUPLING: cross-module reference counts, circular dependencies, the per-function CCN from scripts/complexity.sh.
4. RISKS: current edge cases, what is tested, what is not, invariants to preserve.
5. PLAN: files in change order, tests that must pass before AND after, tier by reversibility x blast radius (file count is only a weak hint). Hand off to /kernel:simplify to execute, which owns the preservation contract and the gate. </refactor_mode>