Debug Loop — Iterative Root Cause Debugging

A 7-phase debugging loop: investigate via causal tree analysis, hypothesize root cause, implement targeted fix, verify with evidence, score against criteria, pressure-test via critique agent, and report with transparency markers. Iterates up to 5x on failures.

Scope Check

Before entering the loop, assess whether it's warranted. The trigger is the verdict category, not a numeric score — research shows LLM-assigned confidence scores are poorly calibrated for open-ended tasks (Tian et al., EMNLP 2023; 49-84% calibration error on open-ended generation).

• Skip the loop if debugging-memory returned KNOWN_FIX — apply the fix directly and verify
• Skip the loop for trivial issues: typos, missing imports, obvious config errors where the cause is immediately clear
• Enter the loop when: verdict is LIKELY_MATCH, WEAK_SIGNAL, or NO_MATCH, the user asks for deep investigation, the initial diagnosis feels superficial, or a previous fix attempt didn't hold

Efficiency

• Terminal output: current phase, key findings (one line each), status changes, failures. No verbose reasoning
• Agent context: minimum needed per job. Pass symptom + relevant findings, not full conversation history
• Load convergence rules reference on demand only when entering iteration

For a repair or restart crossing component boundaries, read change and failure isolation. Verify the shared cause and affected callers; a past incident or a small diff does not establish that the current boundary is adequate.

Phase 1: INVESTIGATE — Gather Evidence and Trace Root Cause

Goal: Understand what's actually failing and why, not just what it looks like.

1. Search debugging memory — use the debugger search MCP tool with the symptom. Note any related incidents
2. Reproduce the issue when feasible — identify exact steps, commands, or conditions that trigger the bug. If the original environment is unavailable, record the causal evidence and limits; distinguish a controlled regression case from reproduction of the original incident.
3. Deploy root-cause-investigator agent — pass the symptom and reproduction steps for causal tree analysis. The agent explores multiple branches (not a single chain), prioritizes by evidence strength, and prunes with evidence
4. Research gate — if the investigator flags unfamiliar error codes, library behavior, or version-specific issues:
   • Search externally (WebSearch, Context7, or documentation)
   • Document what was searched and what was found
   • If search is unavailable, document what SHOULD be searched
5. Assess completeness — does the investigation explain ALL reported symptoms? Check for multi-causal bugs (2+ independent root causes)

Output: Causal tree (with confirmed and pruned branches), reproduction steps, evidence gathered, research performed

Phase 2: HYPOTHESIZE — State the Root Cause

Goal: Commit to a specific, testable hypothesis before writing any fix.

1. State the root cause hypothesis with evidence level:
   • Strong: Multiple evidence types (code, logs, reproduction) all point to this cause
   • Moderate: Some direct evidence plus reasonable inference
   • Weak: Mostly inference, limited direct evidence — consider investigating other branches first
2. Predict verification test: If this hypothesis is correct, what specific test would prove it?
3. Predict related symptoms: What else should be affected if this root cause is real?
4. If multiple hypotheses exist, rank by evidence strength. Pursue the strongest first

Output: Hypothesis statement, evidence level, prediction test, related symptom predictions

Phase 3: FIX — Implement Targeted Change

Goal: Make the simplest adequate change that addresses the causal mechanism across affected supported paths.

1. Compare a symptom patch with a causal repair — trace the existing state owner and affected callers before adding a case-specific exception. A null guard can be correct at a boundary that permits missing data; establish the contract rather than treating every guard as a symptom patch.
2. Keep changes proportional — repair the shared mechanism where needed, preserving supported callers and valid counterexamples. Avoid unrelated cleanup or speculative frameworks; minimum adequate means causal coverage, not the fewest changed lines.
3. Note exactly what was changed and why — this becomes the evidence trail

Output: List of changes with rationale

Phase 4: VERIFY — Test the Fix with Evidence

Goal: Collect concrete evidence that the fix works.

1. Run the prediction test from Phase 2 — does it confirm the hypothesis?
2. Run the original reproduction steps — is the symptom gone?
3. Run related test suite — do existing tests still pass?
4. Check for regressions — run broader test suite if available
5. Verify related symptom predictions — are the predicted effects present?

Each applicable verification step needs evidence: command output, test results, or observable behavior. Mark a genuinely inapplicable check N/A with its scope reason, or a missing required environment/check UNAVAILABLE with the gap. Neither is PASS. "It should work" is not evidence.

Output: Evidence for each verification step

Phase 5: SCORE — Evaluate Against Criteria

Goal: Evidence-based status for each criterion.

Score against these criteria:

Every criterion needs an evidence status. Use PASS with observed evidence, FAIL for an observed unmet criterion, N/A only when genuinely inapplicable to the approved scope, and UNAVAILABLE when required verification cannot be performed. No criterion is PASS without proof, and N/A cannot waive a required check.

If a criterion fails and repair is feasible → enter iteration (Phase 6 rules apply). If all applicable criteria pass, with justified N/A where appropriate → proceed to critique (Phase 6). If required verification is unavailable → finish independent authorized work, then report bounded results and remaining gaps; do not repeat code changes to satisfy a missing environment or claim full verification.

Output: Scorecard with status per criterion, evidence or the specific limitation

Phase 6: CRITIQUE — Pressure-Test Before Declaring Done

Goal: Challenge the fix before the user relies on it.

1. Deploy fix-critique agent with:
   • The symptom
   • The causal tree from investigation (confirmed branch path + pruned branches)
   • The fix (what was changed)
   • The verification evidence
2. Evaluate verdict:
   • APPROVED → proceed to REPORT
   • CHALLENGED → the concerns become input for the next iteration. Route back to INVESTIGATE with the specific challenges as new investigation targets

The critique agent checks 5 things:

• Root cause vs symptom fix
• Symptom coverage (similar bugs elsewhere)
• Regression risk
• Evidence verification
• Causal tree consistency

Phase 7: REPORT — Transparent Status

Goal: Clear, honest summary. No overclaiming.

Transparency Markers

Every item in the report gets one marker:

• ✅ Verified: Checked with evidence (test output, reproduction, command results)
• ⚠️ Assumed: Believed to be true based on reasoning, but not verified with a test
• ❓ Unknown: Not checked at all — explicitly acknowledged gaps

Report Contents

1. Verdict: Fixed within scope when all applicable criteria pass, any N/A is justified, and critique approves. Report partial verification when required evidence is unavailable; report unresolved when failures remain or the iteration limit is reached. Neither partial nor unresolved means fully verified.
2. Root Cause: The identified cause with evidence level
3. Causal Tree: The investigation path — confirmed branches, pruned branches with rejection evidence, any multi-causal findings
4. Fix Applied: What was changed, with rationale
5. Scorecard: Final status per criterion with evidence or a justified N/A/UNAVAILABLE reason
6. Research Used: What was searched externally, what was found, what sources
7. Iteration History (if >1 iteration): What was tried, what failed, what changed between iterations
8. Remaining Gaps: Anything marked ⚠️ or ❓

After Reporting

• Store the incident via the debugger store MCP tool for future retrieval
• Record the outcome via the debugger outcome MCP tool
• Write state to .claude-code-debugger/debug-loop/scorecard.md

Iteration Rules

When any criterion fails or the critique is CHALLENGED, iterate:

1. Diagnose why the criterion failed — don't blind retry
2. Revise the hypothesis if verification disproved it
3. Create a targeted fix plan for the failed mechanism and affected criteria
4. Execute fix
5. Re-verify failed and affected checks — rerun previously passing checks whose evidence the new change can invalidate. Retain unrelated passing evidence only when its source and assumptions remain applicable.
6. Re-score and re-critique

Convergence Detection

Load references/convergence-rules.md for detailed rules and escalation templates.

Summary:

• Same hypothesis fails 2x → escalate to user ("I've tried this approach twice — the hypothesis may be wrong or there's a constraint I'm not seeing")
• Fix A breaks criterion B (oscillation) → flag as coupled issue, present both sides, ask user
• 3+ criteria fail after a fix → systemic issue, stop loop and reassess the approach entirely
• New regression detected → fix is causing side effects, reconsider the approach
• Hard stop at 5 iterations → report what's known and what isn't. Never silently loop beyond 5

State Tracking

Write iteration state to .claude-code-debugger/debug-loop/state.json:

{
  "symptom": "original symptom",
  "iteration": 1,
  "phase": "VERIFY",
  "hypotheses": [
    {
      "iteration": 1,
      "hypothesis": "description",
      "evidence_level": "strong | moderate | weak",
      "result": "confirmed | disproved | partial",
      "evidence": "what was found"
    }
  ],
  "scorecard": [
    {
      "criterion": "symptom_resolved",
      "result": "PASS | FAIL | N/A | UNAVAILABLE",
      "evidence": "summary"
    }
  ],
  "critique_verdict": "APPROVED | CHALLENGED | pending",
  "changes_made": ["file:change summary"]
}

Create the directory with mkdir -p .claude-code-debugger/debug-loop/ before writing.

Anti-Patterns to Avoid