--- name: debug-loop description: Use when a fix didn't hold, `/build-loop:debug` is invoked, the user asks for root cause analysis, memory lookup returns LIKELY_MATCH/WEAK_SIGNAL/NO_MATCH, or Review-B Validate fails. Deep iterative debugging loop — not for known fixes or trivial issues. NOT for blameless postmortem system-lever analysis (use `root-cause-analysis`) or memory search/store (use `debugging-memory`). version: 1.1.0 user-invocable: false --- # 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. ## 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 ## 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. **Domain root-cause catalogs (read directly + point sub-agents at the PATH):** for SwiftUI/macOS "clunky UI" symptoms — choppy/janky panel resize, drag not tracking the cursor, collapse-snap-back, re-render storms, scrunched panes, Picker/list lag — use `references/swiftui-macos-clunky-ui-debugger.html` (13 discrete Root-Cause→Fix slides with real Swift code: onContinuousHover, two-state DragGesture, HSplitView vs NSViewRepresentable, updateNSView feedback-loop guard, re-render storms, animation placement, view-identity resets, NSViewRepresentable minimal pattern, Instruments workflow). It maps symptom→cause→fix directly (e.g. collapse-snap-back → Slide 9 NSViewRepresentable feedback loop → updateNSView guard). When dispatching an implementer, reference the file by PATH so it reads the full methodology — a structured reference FILE read directly beats pasting prose (a sub-agent then carries only your lossy summary). This catalog fixed an NSSplitView resize regression in one pass after two prior failed attempts (easy-terminal 2026-06-08). ## 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 **Output**: Hypothesis statement, evidence level, prediction test, related symptom predictions ## 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** — if you're adding a null check instead of fixing why something is null, you're fixing the symptom 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 **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? Every verification step must produce evidence: command output, test results, or observable behavior. "It should work" is not evidence. **Output**: Evidence for each verification step ## Phase 5: SCORE — Evaluate Against Criteria **Goal**: Objective pass/fail assessment with evidence. Score against these criteria: | # | 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) **Output**: Scorecard with pass/fail per criterion and evidence ## 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 (all criteria pass + critique approved) or Unresolved (iteration limit hit) 2. **Plain-language failure**: What went wrong in normal words 3. **Why it happened**: Symptom -> technical failure -> upstream dependency/interface/process failure -> first controllable system failure 4. **Technical details**: Minimum proof needed to understand the cause 5. **Tradeoffs and impact**: What improves, what risks remain, and who is affected 6. **Prevention control**: Durable test, verifier, trace, gate, protocol, or routing rule 7. **Root cause**: The identified system cause with evidence level 8. **Causal Tree**: The investigation path — confirmed branches, pruned branches with rejection evidence, any multi-causal findings 9. **Fix Applied**: What was changed, with rationale 10. **Scorecard**: Final pass/fail per criterion with evidence 11. **Research Used**: What was searched externally, what was found, what sources 12. **Iteration History** (if >1 iteration): What was tried, what failed, what changed between iterations 13. **Remaining Gaps**: Anything marked ⚠️ or ❓ ### After Reporting > **Durable post-failure RCA:** for the blameless durable-lever pass (creation+escape paths, action-strength hierarchy, lever+actuator, regression artifact, spread check), delegate to the shared `references/root-cause-analysis/` suite. This skill/agent finds and fixes the live issue; that suite is the post-failure prevention layer. - **Store the incident** as a native `.build-loop/issues/*.md` note for future retrieval - **Record the outcome** through standalone Coding Debugger only if that optional plugin supplied the prior incident - **Write state** to `.build-loop/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 targeted fix plan** for failed criteria only 4. **Execute fix** 5. **Re-verify ONLY failed criteria** — don't re-run passing checks 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 ### If stuck — parallel multi-domain assessment When the failure symptom touches multiple layers (e.g. search queries are slow AND results look wrong → database + frontend + API), the linear causal-tree loop can stall. Branch into parallel assessment instead of pursuing one hypothesis serially: 1. Invoke `Skill("build-loop:assess")` with the symptom and the current attempt diff. The bundled `assessment-orchestrator` fans out to relevant domain assessors (`api-assessor` / `database-assessor` / `frontend-assessor` / `performance-assessor`) in parallel. 2. **Model override**: when invoking from the build-loop orchestrator (Opus 4.7), explicitly pass `model: sonnet` to each domain assessor via the subagent dispatch. Without this override, the assessor agents inherit the orchestrator's tier and you get 4 parallel Opus invocations — wasteful for pattern-matching work that Sonnet handles well. Only escalate individual assessors back to Opus if their initial output flags `confidence: low` or `needs_judgment: true`. 3. Aggregate the assessors' ranked findings. The top action becomes the next `HYPOTHESIZE → FIX` plan — feed it back into the loop. When to use parallel assessment vs continuing the linear loop: - Symptom is vague or unclear ("app broken", "something is wrong") → parallel - Multiple domains may be involved ("search is slow and returns wrong results") → parallel - Post-deploy regression with unknown scope → parallel - Symptom is sharp and localized to one layer → continue the linear loop ### Extended capability — cross-domain assessor escalation If the bundled assessor coverage isn't enough (e.g., the failure crosses a domain build-loop's bundled assessors don't cover well, or you need cross-build coordination), escalate via the native debugging skills: ``` Skill("build-loop:debugging-memory") with input { op: "assess", symptom, scope: "global", calledBy: "debug-loop", reason: "stuck-iteration" } ``` The native skill includes domain-specific assessors (api / database / frontend / performance). It uses build-loop local memory by default and may use standalone Coding Debugger for cross-build memory when available; otherwise it falls back to grep across `.build-loop/issues/` and `.build-loop/feedback.md` with narrower coverage. ### State Tracking Write iteration state to `.build-loop/debug-loop/state.json`: ```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", "evidence": "summary" } ], "critique_verdict": "APPROVED | CHALLENGED | pending", "changes_made": ["file:change summary"] } ``` Create the directory with `mkdir -p .build-loop/debug-loop/` before writing. ## Process Flow ``` MEMORY SEARCH → INVESTIGATE → HYPOTHESIZE → FIX → VERIFY → SCORE ↓ All pass? ──yes──→ CRITIQUE ──approved──→ REPORT ↓ ↓ no challenged ↓ ↓ ITERATE ←──────────────┘ (up to 5x) ``` ## Anti-Patterns to Avoid | Anti-Pattern | What to Do Instead | |-------------|-------------------| | Accepting the first explanation | Branch first — identify 2+ plausible causes before pursuing any | | Fixing the symptom | Trace to root cause, fix there | | "This should fix it" | Run the tests, show the output | | Retrying the same approach | If it failed once with the same evidence, it'll fail again. Change the hypothesis | | Declaring victory without evidence | Every claim needs a ✅/⚠️/❓ marker | | Skipping research when stuck | If you don't know why something behaves this way, search for it | | Hiding uncertainty | ⚠️ and ❓ are not failures — they're honest. Hiding them is the failure |