build-loop:debugging-debug-loop

Files (1)

• SKILL.md

SKILL.md (first lines)

<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->

# Debug Loop — Iterative Root Cause Debugging

A 7-phase debugging loop: investigate with structured root-cause methods, 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. Native to build-loop; initially adapted from the debugger workflow lineage.

## Scope Check

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 `build-loop:debugging-memory` returned `KNOWN_FIX` — apply the fix directly and verify
- **Skip the loop** for trivial issues: typos, missing imports, obvious config errors
- **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

## 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** — invoke `build-loop:debugging-memory` with the symptom. Note related incidents from local build-loop memory and optional standalone Coding Debugger memory when available.
2. **Reproduce the issue** — identify exact steps, commands, or conditions that trigger the bug
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.

### Root-Cause Frameworks

Use the lightest framework that fits the failure. Stack frameworks only when the current one stalls.

| Framework | Use when | Output |
|---|---|---|
| 5 Whys | A symptom has a plausible linear chain and needs a controllable system cause | Five-level why-chain ending in a code, test, config, protocol, or process control |
| Causal tree / fault tree | Multiple causes could explain the same symptom | Branches with confirming and pruning evidence |
| Ishikawa / fishbone | The failure may span people/process/code/tooling/data/environment | Category map, then the top 2-3 branches to test |
| Kepner-Tregoe problem analysis | The issue is intermittent, version-specific, or boundary-sensitive | Is/is-not table: affected/unaffected versions, inputs, users, routes, environments |
| Differential diagnosis | Several hypotheses look similar from symptoms alone | Ranked hypotheses plus the discriminating test for each |
| Falsification test | A hypothesis is attractive but under-proven | Smallest test that would disprove it |

For hard fixes, record which framework was used and the decisive evidence. The framework is a thinking scaffold, not a report section unless it clarifies the outcome.

## Phase 2: HYPOTHESIZE — State the Root Cause

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

Start with plain language before implementation detail. State what failed in normal words, then trace visible symptom -> technical failure -> upstream dependency/interface/process failure -> first controllable system failure. Do not use "agent forgot", "agent missed context", or similar actor-blame language as the terminal cause unless you also name the missing system control that allowed it.

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.

## Phase 3: FIX — Implement Targeted Change

**Goal**: Make the minimal change that addresses the hypothesized root cause.

1. **Fix the root cause, not the symptom** — adding a null check instead of fixing why something is null is a symptom fix
2. **Minimal changes** — touch only what's needed. Don't refactor, don't improve, don't clean up
3. **Note exactly what was changed and why** — this becomes the evidence trail

## 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 predicted effects present?

Every verification step must produce evidence: command output, test results, observable behavior. "It should work" is not evidence.

## Phase 5: SCORE — Evaluate Against Criteria

**Goal**: Objective pass/fail with evidence.

| # | Criterion | Method | Pass Condition | Evidence Required |
|---|-----------|--------|----------------|-------------------|
| 1 | Symptom resolved | Reproduction steps | Symptom no longer occurs | Command output or test result |
| 2 | Tests pass | Test suite | All relevant tests pass | Test runner output |
| 3 | No regressions | Broader test suite | No new failures introduced | Test runner output |
| 4 | Root cause addressed | Code review | Fix targets root cause, not symptom | Diff + reasoning |
| 5 | Hypothesis confirmed | Prediction test | Prediction test passes | Test output |

**All criteria must have evidence.** No criterion marked PASS without proof.

If any criterion fails → enter iteration (Phase 6 rules apply).
If all criteria pass → proceed to critique (Phase 6).

## 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** → 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

From tyroneross/build-loop, Apache-2.0.

More from tyroneross/build-loop