Debug - Root Cause Debugging Workflow

Complete debugging workflow that enforces root cause analysis: Investigate → Understand → Reason → Fix.

Overview

Debug combines multiple debugging approaches:

• Codebase investigation - Search for relevant code
• GitHub issues search - Find known issues and workarounds
• Multi-framework reasoning - Apply systematic thinking
• Fix generation - Specific recommendations with code

Prerequisites

# Gemini CLI for AI analysis
pip install google-generativeai
export GEMINI_API_KEY=your_api_key

# gh CLI for GitHub issue search
brew install gh
gh auth login

Debugging Workflows

Full Debug (Recommended for Complex Issues)

# Phase 1: Investigate codebase
rg -l "error pattern" --type ts
rg "relevant_function" -A 10 -B 5

# Phase 2: Search GitHub for known issues
gh search issues "error message" --repo owner/repo --limit 10
gh issue view 123 --repo owner/repo

# Phase 3: Reason about root cause
gemini -m pro -o text -e "" "Given this error and code context, what is the root cause?

Error: [error message]

Code:
\$(cat src/file.ts)

Investigation findings:
- [finding 1]
- [finding 2]

Apply first principles, systematic, and critical thinking frameworks."

# Phase 4: Generate fix
gemini -m pro -o text -e "" "Based on root cause: [cause]

Provide:
1. Specific code fix
2. Before/after code
3. How to verify
4. How to prevent"

Quick Debug (Simple Issues)

# Skip deep reasoning, focus on investigation + fix
rg "error pattern" --type ts -A 5 -B 5

gemini -m pro -o text -e "" "Debug this quickly:

Problem: [description]
Error: [message]

Code:
\$(cat src/problematic-file.ts)

Give me the root cause and fix in 3 sentences."

Debug with Context (Known Files)

# When you already know which files are involved
gemini -m pro -o text -e "" "Debug using these files:

Problem: [description]

File 1:
\$(cat src/file1.ts)

File 2:
\$(cat src/file2.ts)

Provide:
1. Root cause
2. Specific fix with line numbers
3. Verification steps"

Comprehensive Diagnosis (Complex Issues)

# Parallel investigation of multiple sources

# Terminal 1: Codebase search
rg "error" --type ts --stats > /tmp/codebase.txt &

# Terminal 2: GitHub issues
gh search issues "error" --limit 20 > /tmp/github.txt &

# Terminal 3: Git history
git log --oneline --all -S "problematic_function" > /tmp/history.txt &

wait

# Synthesize findings
gemini -m pro -o text -e "" "Synthesize these diagnostic findings:

Codebase:
\$(cat /tmp/codebase.txt)

GitHub Issues:
\$(cat /tmp/github.txt)

Git History:
\$(cat /tmp/history.txt)

Provide unified diagnosis with:
1. Most likely root cause
2. Confidence level
3. Key evidence
4. Differential diagnosis
5. Recommended action"

Root Cause Protocol

Always follow this hierarchy:

1. INVESTIGATE - Search for evidence first
2. UNDERSTAND - Read relevant code
3. REASON - Apply systematic thinking
4. FIX - Only then propose changes

Forbidden Shortcuts

Investigation Commands

Codebase Search

# Find error patterns
rg "throw.*Error" --type ts -A 3

# Find function definitions
rg "function functionName|const functionName" --type ts

# Find usages
rg "functionName\(" --type ts

# Find recent changes
git log --oneline -20 --all -- src/problematic/
git diff HEAD~5 -- src/problematic/

GitHub Issue Search

# Search issues
gh search issues "error message" --repo owner/repo --state all

# View issue details
gh issue view 123 --repo owner/repo --comments

# Search across multiple repos
for repo in repo1 repo2 repo3; do
  gh search issues "error" --repo owner/$repo --limit 5
done

Log Analysis

# Find logs first
find . -name "*.log" -type f

# Tail recent logs
tail -100 logs/app.log | grep -i error

# Search logs for patterns
grep -n "ERROR\|WARN" logs/*.log | tail -50

Framework-Based Reasoning

First Principles

gemini -m pro -o text -e "" "Apply first principles to this bug:

Problem: [description]

Questions:
1. What is this code supposed to do?
2. What is it actually doing?
3. What assumptions are being made?
4. Which assumption is wrong?"

Systematic Analysis

gemini -m pro -o text -e "" "Systematically analyze:

Problem: [description]

Walk through:
1. Input → What data enters?
2. Processing → What transformations?
3. State → What state changes?
4. Output → What comes out?
5. Where does expected diverge from actual?"

Critical Thinking

gemini -m pro -o text -e "" "Challenge assumptions:

Problem: [description]

For each potential cause:
- What evidence supports it?
- What evidence contradicts it?
- What would we expect to see if true?
- Can we rule it out?"

Output Format

A debug session should produce:

## ROOT CAUSE
Single sentence identifying the actual cause.

## CONFIDENCE
high | medium | low

## FIX
Specific code changes:
- File: src/file.ts
- Line: 42
- Before: `oldCode()`
- After: `newCode()`

## VERIFICATION
How to verify the fix works:
1. Run test: `npm test -- specific.test.ts`
2. Manual check: [steps]

## PREVENTION
How to prevent this in the future:
- Add validation at boundary
- Add regression test

Best Practices

1. Logs first - Read logs before reading code
2. Evidence required - No fix without citing specific evidence
3. One cause - Find THE root cause, not symptoms
4. Verify hypothesis - Test your theory before fixing
5. Prevent recurrence - Add tests for the failure mode
6. Document findings - Capture what you learned