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

bash
1# Gemini CLI for AI analysis
2pip install google-generativeai
3export GEMINI_API_KEY=your_api_key
4
5# gh CLI for GitHub issue search
6brew install gh
7gh auth login

Debugging Workflows

Full Debug (Recommended for Complex Issues)

bash
1# Phase 1: Investigate codebase
2rg -l "error pattern" --type ts
3rg "relevant_function" -A 10 -B 5
4
5# Phase 2: Search GitHub for known issues
6gh search issues "error message" --repo owner/repo --limit 10
7gh issue view 123 --repo owner/repo
8
9# Phase 3: Reason about root cause
10gemini -m pro -o text -e "" "Given this error and code context, what is the root cause?
11
12Error: [error message]
13
14Code:
15\$(cat src/file.ts)
16
17Investigation findings:
18- [finding 1]
19- [finding 2]
20
21Apply first principles, systematic, and critical thinking frameworks."
22
23# Phase 4: Generate fix
24gemini -m pro -o text -e "" "Based on root cause: [cause]
25
26Provide:
271. Specific code fix
282. Before/after code
293. How to verify
304. How to prevent"

Quick Debug (Simple Issues)

bash
1# Skip deep reasoning, focus on investigation + fix
2rg "error pattern" --type ts -A 5 -B 5
3
4gemini -m pro -o text -e "" "Debug this quickly:
5
6Problem: [description]
7Error: [message]
8
9Code:
10\$(cat src/problematic-file.ts)
11
12Give me the root cause and fix in 3 sentences."

Debug with Context (Known Files)

bash
1# When you already know which files are involved
2gemini -m pro -o text -e "" "Debug using these files:
3
4Problem: [description]
5
6File 1:
7\$(cat src/file1.ts)
8
9File 2:
10\$(cat src/file2.ts)
11
12Provide:
131. Root cause
142. Specific fix with line numbers
153. Verification steps"

Comprehensive Diagnosis (Complex Issues)

bash
1# Parallel investigation of multiple sources
2
3# Terminal 1: Codebase search
4rg "error" --type ts --stats > /tmp/codebase.txt &
5
6# Terminal 2: GitHub issues
7gh search issues "error" --limit 20 > /tmp/github.txt &
8
9# Terminal 3: Git history
10git log --oneline --all -S "problematic_function" > /tmp/history.txt &
11
12wait
13
14# Synthesize findings
15gemini -m pro -o text -e "" "Synthesize these diagnostic findings:
16
17Codebase:
18\$(cat /tmp/codebase.txt)
19
20GitHub Issues:
21\$(cat /tmp/github.txt)
22
23Git History:
24\$(cat /tmp/history.txt)
25
26Provide unified diagnosis with:
271. Most likely root cause
282. Confidence level
293. Key evidence
304. Differential diagnosis
315. 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

bash
1# Find error patterns
2rg "throw.*Error" --type ts -A 3
3
4# Find function definitions
5rg "function functionName|const functionName" --type ts
6
7# Find usages
8rg "functionName\(" --type ts
9
10# Find recent changes
11git log --oneline -20 --all -- src/problematic/
12git diff HEAD~5 -- src/problematic/

GitHub Issue Search

bash
1# Search issues
2gh search issues "error message" --repo owner/repo --state all
3
4# View issue details
5gh issue view 123 --repo owner/repo --comments
6
7# Search across multiple repos
8for repo in repo1 repo2 repo3; do
9  gh search issues "error" --repo owner/$repo --limit 5
10done

Log Analysis

bash
1# Find logs first
2find . -name "*.log" -type f
3
4# Tail recent logs
5tail -100 logs/app.log | grep -i error
6
7# Search logs for patterns
8grep -n "ERROR\|WARN" logs/*.log | tail -50

Framework-Based Reasoning

First Principles

bash
1gemini -m pro -o text -e "" "Apply first principles to this bug:
2
3Problem: [description]
4
5Questions:
61. What is this code supposed to do?
72. What is it actually doing?
83. What assumptions are being made?
94. Which assumption is wrong?"

Systematic Analysis

bash
1gemini -m pro -o text -e "" "Systematically analyze:
2
3Problem: [description]
4
5Walk through:
61. Input → What data enters?
72. Processing → What transformations?
83. State → What state changes?
94. Output → What comes out?
105. Where does expected diverge from actual?"

Critical Thinking

bash
1gemini -m pro -o text -e "" "Challenge assumptions:
2
3Problem: [description]
4
5For each potential cause:
6- What evidence supports it?
7- What evidence contradicts it?
8- What would we expect to see if true?
9- Can we rule it out?"

Output Format

A debug session should produce:

markdown
1## ROOT CAUSE
2Single sentence identifying the actual cause.
3
4## CONFIDENCE
5high | medium | low
6
7## FIX
8Specific code changes:
9- File: src/file.ts
10- Line: 42
11- Before: `oldCode()`
12- After: `newCode()`
13
14## VERIFICATION
15How to verify the fix works:
161. Run test: `npm test -- specific.test.ts`
172. Manual check: [steps]
18
19## PREVENTION
20How to prevent this in the future:
21- Add validation at boundary
22- 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