
investigate
Debug and investigate code issues using search and AI analysis. Use when stuck on bugs, tracing execution flow, or understanding complex code.
- Installs
- 67
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/johnlindquist/claude --skill investigate- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads investigate automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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
FAQ
What does the investigate skill do?
Debug and investigate code issues using search and AI analysis. Use when stuck on bugs, tracing execution flow, or understanding complex code.
How do I install investigate?
Run npx skills add https://github.com/johnlindquist/claude --skill investigate in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/investigate/ (personal) or .claude/skills/investigate/ (project).
Which AI agents can use investigate?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is investigate safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains investigate?
It is published by johnlindquist in johnlindquist/claude. It has 67 recorded installs.
More from johnlindquist/claude
gemini-image
johnlindquist/claude
Analyze images using Gemini's vision capabilities. Use for image analysis, text extraction from screenshots, and visual content understanding.
brainstorm
johnlindquist/claude
Open the skill to read its SKILL.md instructions.
deepwiki
johnlindquist/claude
Query DeepWiki for repository documentation and structure. Use to understand open source projects, find API docs, and explore codebases.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.