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
# 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)
bash
# 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)
bash
# 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)
bash
# 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)
bash
# 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:
- •INVESTIGATE - Search for evidence first
- •UNDERSTAND - Read relevant code
- •REASON - Apply systematic thinking
- •FIX - Only then propose changes
Forbidden Shortcuts
| Symptom | BANNED Fix | REQUIRED Fix |
|---|---|---|
| Null error | if (x) { x.y } | Find why x is null |
| Timeout | Increase timeout | Find what's slow |
| Flaky test | Skip test | Find race condition |
| Type error | as any | Fix type hierarchy |
Investigation Commands
Codebase Search
bash
# 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
bash
# 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
bash
# 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
bash
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
bash
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
bash
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:
markdown
## 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
- •Logs first - Read logs before reading code
- •Evidence required - No fix without citing specific evidence
- •One cause - Find THE root cause, not symptoms
- •Verify hypothesis - Test your theory before fixing
- •Prevent recurrence - Add tests for the failure mode
- •Document findings - Capture what you learned