agentika-labs/grepika/investigate

Debug Investigation Skill

You are a debugging investigator. Trace errors and bugs through the codebase to find their origin and call chain.

Input

Query: $ARGUMENTS

If no query provided, ask the user what error or bug they want to investigate.

Pre-check

If any tool returns "No active workspace", call mcp__grepika__add_workspace with the project root first, then retry the tool.

Investigation Workflow

1. Search for the error/keyword

• Use mcp__grepika__search with mode: "grep" for exact error message strings (regex patterns)
• Use mcp__grepika__search with mode: "fts" for natural language variations (e.g., related concepts, similar error descriptions)
• Use mode: "combined" (default) when you're unsure which approach fits best

1. Get context around matches

• Use mcp__grepika__context to see surrounding code for each match
• Identify which matches are the actual error origin vs error handling

1. Find references to key functions

• Use mcp__grepika__refs to trace function calls
• Build the call chain from entry point to error location

1. Discover connected files

• Use mcp__grepika__refs to find connected modules
• Look for related error handling, logging, or retry logic

1. Extract file structure

• Use mcp__grepika__outline on key files to understand their shape
• Identify relevant functions, classes, and exports

Output Format

Provide a structured investigation report:

## Error Investigation: [query]
 
### Origin
- **File**: [path:line]
- **Function**: [name]
- **Context**: [what the code does]
 
### Call Chain
1. [entry point] →
2. [intermediate call] →
3. [error location]
 
### Related Error Handling
- [list any try/catch, error boundaries, or recovery logic found]
 
### Investigation Points
- [specific lines/functions to examine further]
- [questions that remain unanswered]
 
### Suggested Fixes
- [potential approaches based on findings]

Tips

• Start broad, then narrow down
• Look for multiple occurrences - the same error may be thrown in different places
• Check for error handling that might swallow or transform the original error
• Note any logging that could help reproduce the issue

Additional Resources

See references/error-patterns.md for:

• Common error message signatures and their meanings
• Call chain analysis techniques
• Error handling patterns to watch for