---
name: investigate
description: |
  This skill should be used when the user asks to "investigate a bug",
  "trace an error", "debug this issue", "find where this error comes from",
  or mentions keywords related to error tracing and bug investigation.
version: 1.1.0
compatibility: "Requires grepika MCP server."
disable-model-invocation: true
context: fork
agent: Explore
model: haiku
allowed-tools:
  - mcp__grepika__search
  - mcp__grepika__refs
  - mcp__grepika__outline
  - mcp__grepika__context
  - mcp__grepika__get
  - mcp__grepika__graph
  - mcp__grepika__structural_search
  - mcp__grepika__add_workspace
---

# 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

2. **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

3. **Find references to key functions**
   - Use `mcp__grepika__refs` to trace function calls
   - Build the call chain from entry point to error location

4. **Discover connected files**
   - Use `mcp__grepika__refs` to find connected modules
   - Look for related error handling, logging, or retry logic

5. **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