Bug Diagnostic Loop
Relevant source files
The following files were used as context for generating this wiki page:
The Bug Diagnostic Loop is a disciplined procedure for identifying root causes of hard bugs and performance regressions. It operates as a strict sequence of phases: reproduction, minimization, hypothesis generation, instrumentation, fixing, and regression testing. This loop ensures that developers address the original trigger of a failure rather than merely treating visible symptoms.
Sources: skills/diagnose/SKILL.md:1-5
Diagnostic Workflow Overview
The diagnostic loop prioritizes the construction of a deterministic pass/fail signal. It follows a root-cause-first gate, meaning no production fix begins until the symptom is reproduced and the source trigger is traced. The process moves through eight distinct phases, where skipping phases requires explicit justification.
The diagnostic workflow enforces a sequential progression from reproduction to final cleanup.
Sources: skills/diagnose/SKILL.md:7-14, CLAUDE.md:28-31
Phase 1: Feedback Loop Construction
This phase focuses on creating a fast, deterministic, and runnable signal. A high-quality loop allows for automated bisection and hypothesis testing. You must iterate on the loop to make it faster (narrowing test scope) and more deterministic (pinning time or seeding RNG).
Methods for Constructing Feedback Loops
| Method | Description |
|---|---|
| Failing Test | Unit, integration, or e2e tests reaching the bug seam. |
| Curl/HTTP Script | Direct requests against a running development server. |
| CLI Invocation | Execution with fixture input and stdout diffing. |
| Headless Browser | Playwright/Puppeteer scripts driving the UI. |
| Replay Trace | Replaying captured network payloads or event logs. |
| Bisection Harness | Automation of git bisect run between known states. |
| HITL Bash Script | Human-in-the-loop scripts using hitl-loop.template.sh. |
Sources: skills/diagnose/SKILL.md:16-43
Phase 2 & 3: Reproduction and Tracing
Reproduction requires watching the bug appear while confirming it matches the user-reported failure mode exactly. Once reproduced, the developer traces backward from the symptom to the original trigger.
Tracing moves backward through the execution stack to find the source of invalid state.
Sources: skills/diagnose/SKILL.md:58-74
Phase 4 & 5: Pattern Analysis and Hypothesising
Pattern analysis involves checking recent commits, dependencies, and environment changes. You must generate 3–5 ranked, falsifiable hypotheses before testing. Each hypothesis must follow the format: "If X is the cause, then changing Y will make the bug disappear."
Sources: skills/diagnose/SKILL.md:88-106
Phase 6: Instrumentation
Instrumentation uses targeted probes to test predictions. Probes should be limited to one variable at a time to avoid bundling multiple changes.
- Debugger/REPL: Preferred over logs for environmental support.
- Targeted Logs: Placed at boundaries to distinguish hypotheses.
- Unique Tags: All debug logs must use a unique prefix (e.g.,
[DEBUG-...]) for easy cleanup. - Condition-based Waiting: Use real state changes or events instead of arbitrary sleeps for async failures.
Sources: skills/diagnose/SKILL.md:112-126
Phase 7: Fix and Regression Test
A regression test must be written before the fix, provided a correct seam exists. A correct seam exercises the real bug pattern as it occurs at the call site. If no correct seam exists, this indicates an architectural deficiency that should be addressed via improve-codebase-architecture.
Sources: skills/diagnose/SKILL.md:131-147, skills/production-preflight/SKILL.md:46-51
Phase 8: Cleanup and Post-mortem
The loop concludes with a checklist to ensure the repository remains clean and the root cause is documented.
- Re-run Phase 1 Loop: Ensure the original reproduction no longer fails.
- Verify Regression Test: Confirm the new test passes.
- State Root Cause: Document the traced source in the commit/PR message.
- Remove Instrumentation: Grep for and delete all
[DEBUG-...]markers. - Identify Prevention: Determine if architectural changes (e.g., untangling callers) could have prevented the bug.
Sources: skills/diagnose/SKILL.md:154-167
Integration with Production Workflow
The diagnostic loop is a mandatory prerequisite for behavior bugs within the standard production workflow. The repo-production-workflow skill invokes diagnose for bugs, regressions, and performance problems before any fix begins. Preflight proof for a behavior bug must name the reproduced symptom, traced root cause, and testable hypothesis derived from this loop.
Sources: skills/repo-production-workflow/SKILL.md:42-45, skills/production-preflight/SKILL.md:40-44