---
name: debugging-workflow
description: >
  Systematic, hypothesis-driven debugging workflow: reproduction, isolation, root cause identification,
  surgical fixes, and regression prevention. Use when diagnosing bugs, unexpected runtime errors,
  failing tests, or when asked to debug an issue.
concerns: [system-one-balance]
---

# Debugging Workflow

A systematic, disciplined protocol for finding and fixing software bugs efficiently without guessing or introducing collateral regressions.

---

## Phase 0: Setup and Protocols

1. Invariants:
   - Never apply random fixes hoping one works. Every fix must be preceded by an identified root cause.
   - Prefer minimal surgical edits over wide refactors during bug resolution.
   - Every resolved bug should ideally be pinned with a reproduction test.

---

## Phase 1: Ingest and Check

1. **Information Gathering**:
   - Inspect the verbatim error message, stack trace, and relevant log streams.
   - Identify the exact file and line where failure manifests.
   - Record the expected vs. actual behavior and environmental conditions.
2. **Reproduction & Isolation**:
   - Determine whether the bug is reliably reproducible.
   - Construct a minimal reproduction case or failing test.
   - Identify recent changes: review `git diff HEAD~5..HEAD` or recent commits if the issue is a regression.

---

## Phase 2: Processing (Core Logic)

### Step 1: Formulate and Rank Hypotheses
Classify the issue into primary failure categories:
- **Logic Errors**: Off-by-one, inversion of boolean operators, missing edge cases.
- **Data Errors**: Null/undefined references, schema divergence, malformed encodings.
- **State & Concurrency**: Race conditions, stale cache, incomplete state mutation.
- **Integration Errors**: API contract drift, network timeouts, environment configuration.

Formulate the most probable hypothesis and design a quick diagnostic probe to validate or falsify it.

### Step 2: Diagnostic Probing
- Add focused diagnostic logging or evaluate intermediate states.
- Use binary search / bisection when isolating faults in large code paths.
- Check assumptions at subsystem boundaries: inspect inputs immediately before and outputs immediately after the failure site.

### Step 3: Implement Minimal Surgical Fix
- Address the underlying defect rather than masking the symptom (e.g. don't simply wrap with a silent `try/catch` or null check if an invariant was violated upstream).
- Keep changes minimal and localized to the responsible subsystem.

### Step 4: Regression Defense
- Execute test suites to confirm no existing functionality broke.
- Add or update an automated unit/integration test capturing the failure condition.

---

## Phase 3: The System One Balance Pass

- **Augment, Don't Handcuff**:
  - If full stack trace and error context are already visible in the conversation, do NOT ask the user redundant intake questions ("Can you provide the logs?"). Proceed directly to diagnosis.
  - Do NOT rewrite unrelated modules or refactor working code while fixing a bug.
  - Fix fast; reserve deep architectural audits for dedicated refactoring passes.

---

## Phase 4: Output Execution & Verification

Deliver the debugging report with:
1. **Root Cause**: Crisp explanation of why the failure occurred.
2. **Surgical Diff**: The exact code changes applied.
3. **Verification**: Command executed or test output demonstrating the fix.
4. **Prevention**: Regression test added to guard against recurrence.