Agent skill
investigate
Debug and investigate code issues using search and AI analysis. Use when stuck on bugs, tracing execution flow, or understanding complex code.
Install this agent skill to your Project
npx add-skill https://github.com/johnlindquist/claude/tree/main/skills/investigate
SKILL.md
Investigation Toolkit
Debug issues through systematic search and AI-powered analysis.
Prerequisites
# ripgrep for fast search
brew install ripgrep
# Gemini for analysis
pip install google-generativeai
export GEMINI_API_KEY=your_api_key
Search Commands
ripgrep Basics
# Search for pattern
rg "pattern" src/
# Case insensitive
rg -i "error" src/
# Whole word
rg -w "user" src/
# File types
rg -t ts "function" src/
rg -t py "def " src/
# Exclude patterns
rg "TODO" --glob "!node_modules"
# Show context
rg -C 3 "error" src/ # 3 lines before and after
rg -B 5 "crash" src/ # 5 lines before
rg -A 5 "crash" src/ # 5 lines after
# Just filenames
rg -l "pattern" src/
# Count matches
rg -c "pattern" src/
Finding Definitions
# Function definitions (TypeScript)
rg "function\s+functionName" src/
rg "(const|let|var)\s+functionName\s*=" src/
rg "export\s+(async\s+)?function\s+\w+" src/
# Class definitions
rg "class\s+ClassName" src/
# Interface/Type definitions
rg "(interface|type)\s+TypeName" src/
Tracing Usage
# Where is this function called?
rg "functionName\(" src/
# Where is this imported?
rg "import.*functionName" src/
# Where is this exported?
rg "export.*functionName" src/
Investigation Patterns
Bug Investigation
# 1. Search for error message
rg "exact error message" .
# 2. Find where error is thrown
rg "throw.*Error" src/ -C 3
# 3. Trace the function
rg "functionThatFails" src/ -C 5
# 4. Check recent changes
git log --oneline -20 --all -- src/problematic-file.ts
git diff HEAD~5 -- src/problematic-file.ts
Trace Execution Flow
#!/bin/bash
ENTRY_POINT=$1
echo "=== Entry Point ==="
rg -A 10 "export.*$ENTRY_POINT" src/
echo "=== Called Functions ==="
rg -o "\w+\(" src/$ENTRY_POINT*.ts | sort -u
echo "=== Dependencies ==="
rg "^import" src/$ENTRY_POINT*.ts
AI-Assisted Debugging
# Analyze error with context
ERROR="Your error message here"
CODE=$(cat problematic-file.ts)
gemini -m pro -o text -e "" "Debug this error:
ERROR: $ERROR
CODE:
$CODE
Provide:
1. Most likely cause
2. How to verify
3. How to fix
4. How to prevent in future"
Hypothesis Testing
# Generate hypotheses
gemini -m pro -o text -e "" "Given this bug symptom:
SYMPTOM: [describe what's happening]
CONTEXT: [relevant code/system info]
Generate 5 hypotheses ranked by likelihood, with a test for each."
# Then test each hypothesis
rg "hypothesis-related-pattern" src/
Common Investigations
Find All Error Handling
rg "catch|\.catch|try\s*{" src/ -t ts
rg "throw\s+new" src/ -t ts
Find API Endpoints
rg "(get|post|put|delete|patch)\s*\(" src/ -i
rg "router\.(get|post|put|delete)" src/
rg "@(Get|Post|Put|Delete)" src/
Find Database Queries
rg "(SELECT|INSERT|UPDATE|DELETE)" src/ -i
rg "\.query\(|\.execute\(" src/
rg "prisma\.\w+\.(find|create|update|delete)" src/
Find Configuration
rg "process\.env\." src/
rg "(config|settings)\[" src/
rg "getenv|os\.environ" src/ -t py
Find Security Issues
# SQL injection potential
rg "query.*\+.*\"|'.*\+" src/
# Hardcoded secrets
rg "(password|secret|key|token)\s*=\s*['\"]" src/ -i
# Unsafe eval
rg "eval\(" src/
Deep Investigation Script
#!/bin/bash
# investigate.sh - Comprehensive code investigation
TERM=$1
echo "=== Investigating: $TERM ==="
echo ""
echo "### Definitions ###"
rg "^(export\s+)?(function|const|class|interface|type)\s+$TERM" src/
echo ""
echo "### Usage ###"
rg "$TERM" src/ --stats | head -50
echo ""
echo "### Recent Changes ###"
git log --oneline -10 -S "$TERM"
echo ""
echo "### Blame ###"
for f in $(rg -l "$TERM" src/); do
echo "--- $f ---"
git blame -L "/$TERM/,+5" "$f" 2>/dev/null | head -10
done
Best Practices
- Start with the error - Search for exact message first
- Expand context - Use
-C,-B,-Afor surrounding code - Check history -
git log -Sfinds when code was introduced - Use AI for complex - When pattern matching isn't enough
- Document findings - Note what you discover
- Test hypotheses - Verify before assuming
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
testgen
Generate tests using AI and run test suites. Use for generating unit tests, running coverage reports, and mutation testing.
article
Generate technical articles and documentation using AI. Use for writing blog posts, documentation, and technical content.
packx
Bundle code context for AI. ALWAYS use --limit 49k unless user explicitly requests otherwise. Use for creating shareable code bundles and preparing context for LLMs.
long-agent
Manage long-running agent sessions. Use for tracking progress in extended tasks, maintaining context across long sessions, and managing multi-step workflows.
db
Database operations for SQLite, PostgreSQL, and MySQL. Use for queries, schema inspection, migrations, and AI-assisted query generation.
debug
Unified debugging workflow enforcing root cause protocol. Investigate → Understand → Reason → Fix. Use when debugging bugs, errors, or unexpected behavior.
Didn't find tool you were looking for?