debug

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

```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

```

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"

```

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

| 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 |

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

```

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?"

```

A debug session should produce:

```markdown

Single sentence identifying the actual cause.

high | medium | low

Specific code changes:

• File: src/file.ts
• Line: 42
• Before: oldCode()
• After: newCode()

How to verify the fix works:

1. Run test: npm test -- specific.test.ts
2. Manual check: [steps]

How to prevent this in the future:

• Add validation at boundary
• Add regression test

```

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