Debug

Debug

Purpose: Systematic bug investigation and fixing Phases: Reproduce → Analyze → Narrow → Fix → Verify Usage: /debug [scope flags] <bug description>

Iron Laws

1. NO FIXES WITHOUT ROOT CAUSE — Never apply a fix without first identifying and confirming the root cause. Guessing is not debugging.
2. ANALYZE FIRST, FIX SECOND — AI excels at analysis but struggles when simultaneously diagnosing and fixing. Complete all analysis before proposing any fix.
3. EVERY BUG FIX NEEDS A REGRESSION TEST — A fix without a test is a fix that will break again.
4. THREE FAILURES MEANS RETHINK — If 3 fix attempts fail, the bug is a design problem. Stop patching and escalate.

When to Use

• Bug reports or error messages
• Test failures with unclear cause
• Unexpected runtime behavior
• Performance regressions

When NOT to Use

• Known fix, just needs implementation → /implement
• Adding new functionality → /implement
• Investigating code without a bug → /explore

Never Do

• Never suppress an error to "fix" it — Catching and ignoring is hiding, not fixing
• Never fix symptoms instead of root cause — If the symptom is a null pointer, the root cause is why it's null
• Never apply a fix you don't understand — "It works but I don't know why" means it will break again
• Never make multiple changes at once — Change one thing, verify, then change the next

Scope Flags

Note: Command examples use npm as default. Adapt to the project's package manager per ai-assistant-protocol — Project Commands.

Phase 1: Reproduce

Mode: Read-only — gather symptoms and establish reproduction.

Step 1.1: Gather Symptoms

## Bug Investigation

1. **What's happening?** Expected vs. Actual
2. **When does it occur?** Always / Sometimes / Specific conditions
3. **Reproduction steps?**
4. **Recent changes?**

Wait for response.

Step 1.2: Establish Minimal Reproduction

Before investigating, identify the smallest possible reproduction case:

• What's the minimal input that triggers the bug?
• Can the bug be reproduced in a test?
• If a test reproduces it, that becomes the regression test.

Step 1.3: Confirm Understanding

**Issue:** [restate problem]
**Conditions:** [when it happens]
**Impact:** [who/what affected]

**Confirm understanding:** (yes / correct / clarify)

GATE: Wait for confirmation.

Phase 2: Analyze

Mode: Read-only — form hypotheses. Do NOT propose fixes yet.

Step 2.1: Form Hypotheses

## Hypotheses

1. **[Hypothesis A]** — Why: [reasoning] — Check: [how to verify]
2. **[Hypothesis B]** — Why: [reasoning] — Check: [how to verify]

Step 2.2: Investigate

Classify the bug by failure mode and use backward tracing to find the root cause (see references/debugging-techniques.md for failure taxonomy, and references/root-cause-tracing.md for the backward tracing methodology).

Context-Aware References

Load debugging references based on failure category:

Use the debugging decision tree to select strategy:

Step 2.3: Compare Working vs. Broken

Search for similar functionality that works correctly. Document differences.

git log --oneline -20 -- path/to/broken.ts

Phase 3: Narrow

Mode: Read-only — converge on root cause with user input.

Step 3.1: Present Analysis

## Analysis Results

**Investigated:** [what was checked]
**Eliminated:** [hypotheses ruled out and why]
**Most likely:** [remaining hypothesis with evidence]

Step 3.2: Narrow Focus with User

Ask the user to help eliminate hypotheses:

## Remaining Hypotheses

1. [Hypothesis X] — Evidence: [what supports it]
2. [Hypothesis Y] — Evidence: [what supports it]

**Narrow further:** (eliminate a hypothesis or suggest additional checks)

Step 3.3: Confirm Root Cause

## Root Cause

**Location:** `path/to/file.ts:42`
**Problem:** [what's wrong]
**Why:** [explanation]
**Evidence:** [findings that confirm this]

**Confirm root cause:** (yes / no / need more evidence)

GATE: Wait for confirmation before proposing fix.

Phase 4: Fix

Mode: Full access — implement the approved fix.

Step 4.1: Propose Fix

## Fix Plan

**Root Cause:** [brief summary]
**Solution:** [what will change]
**Files:** `path/to/file.ts` — [fix description]
**Regression Test:** Test for [scenario]
**Security impact:** [Does the fix touch input handling, auth, or data access? If yes, verify no security regression]
**Risks:** [any concerns]

---
**Approve fix?** (yes / no / modify)

GATE: Do NOT implement until user approves.

Step 4.2: Implement Fix

1. Apply fix — one change at a time
2. Run typecheck after change
3. Validate at multiple layers (see references/defense-in-depth.md for four-layer validation and related code audit)

Step 4.3: Add Regression Test

REQUIRED. The test should reproduce the bug scenario and assert correct behavior:

it('should [correct behavior] when [bug trigger condition]', () => {
  // Arrange: conditions that triggered the bug
  // Act: action that previously failed
  // Assert: correct behavior
});

Escalation Rule

Present an escalation report:

## Escalation Report
**Bug:** [description]
**Attempts:** 3
**Hypotheses Tested:** [list with evidence for/against]
**Remaining Theories:** [what hasn't been ruled out]
**Suggested Next Steps:** [what a human should investigate]
**Architectural Concern:** [why this may be a design problem]

Phase 5: Verify

Mode: Testing + git operations.

Step 5.1: Run All Tests

npm run test -- path/to/file.spec.ts   # Regression test first
npm run test -- [affected-pattern]      # Related tests
npm run typecheck
npm run lint

Step 5.2: Verification Report

## Verification

| Check | Status |
|-------|--------|
| Regression test | ✓ Pass |
| Related tests | ✓ Pass (N tests) |
| Type check | ✓ Pass |
| Lint | ✓ Pass |

**Verify fix externally:** (confirmed working / still broken / partially fixed)

GATE: All tests must pass. Wait for user verification.

Step 5.3: Commit

Present commit message with root cause explanation and Fixes #issue reference.

GATE: Wait for explicit approval before committing.

Quick Reference

Acceptance Tests

Converted and distributed by TomeVault — claim your Tome and manage your conversions.