investigate

name	investigate
description	Deep investigation of errors, bugs, or codebase questions without making any code changes. Use when user mentions investigate, understand, explore, analyze, or pastes error tracebacks. Spawns parallel subagents for comprehensive exploration.
hooks	{"PreToolUse":[{"matcher":"*","hooks":[{"type":"command","command":"echo '🔍 [SKILL: investigate] Starting investigation...'","once":true}]}]}

Investigation Skill

Perform deep codebase investigation without making any changes. This skill uses parallel subagents to explore multiple aspects simultaneously.

When to Use

• User pastes an error traceback and wants root cause analysis
• User wants to understand how a system/module works
• User asks "how did tests miss this" or similar
• User says "investigate", "explore", "understand", or "analyze"
• User explicitly says "do not change any code"

GitHub Issue Input

If the ARGUMENTS contain a GitHub issue reference, call fetch_github_issue via the MCP tool before beginning any analysis. Use the returned content field as the investigation topic.

Detection — scan ARGUMENTS for any of these patterns:

• Full URL: https://github.com/{owner}/{repo}/issues/{N} (e.g. https://github.com/acme/project/issues/42)
• Shorthand: {owner}/{repo}#{N} (e.g. acme/project#42)
• Bare number with default repo: #N or N when github.default_repo is configured
• Orchestrator hint line: a line containing GitHub Issue: followed by a URL or shorthand

Behavior:

• If the entire ARGUMENTS is an issue reference → call fetch_github_issue and use the returned content as the complete investigation topic.
• If ARGUMENTS contains a trailing GitHub Issue: {url} line (added by the pipeline orchestrator) → call fetch_github_issue for that URL and append the returned content as supplementary context appended after the investigation topic.
• Call with include_comments: true for full context.
• If fetch_github_issue returns success: false, log the failure and proceed with the raw ARGUMENTS as-is.

Critical Constraints

NEVER:

• Modify any source code files
• Suggest backward compatibility solutions
• Suggest fallbacks that hide errors
• Create files outside temp/investigate/ directory
• Choose or accept approaches, solutions, and/or fixes that are chosen simply because they are easier

ALWAYS:

• Use subagents for parallel exploration
• Use model: "sonnet" when spawning all subagents via the Task tool
• Write findings as a markdown report with unique name to temp/investigate/ directory (relative to the current working directory)
• Identify how tests missed the issue (if applicable)
• Check for similar existing patterns in codebase
• Ensure approaches, solutions, and fixes are the appropriate long-term solutions with proper architecture

Investigation Workflow

Path-existence guard: Before issuing a Read call on a path that is not guaranteed to exist (e.g., plan file arguments, temp/investigate/ reports, external file references), use Glob or ls to confirm the path exists first. This prevents ENOENT errors that cascade into sibling parallel-call cancellations.

Step 0.5 — Code-Index Initialization (required before any code-index tool call)

Call set_project_path with the repo root where this skill was invoked (not a worktree path):

mcp__code-index__set_project_path(path="{PROJECT_ROOT}")

Code-index tools require project-relative paths. Always use paths like:

src/<your_package>/some_module.py

NOT absolute paths like:

/absolute/path/to/src/<your_package>/some_module.py

Note: Code-index tools (find_files, search_code_advanced, get_file_summary, get_symbol_body) are only available when the code-index MCP server is configured. If set_project_path returns an error, fall back to native Glob and Grep tools for the same searches — they provide equivalent results without the code-index server.

Agents launched via run_skill inherit no code-index state from the parent session — this call is mandatory at the start of every headless session that uses code-index tools.

Step 1: Parse the Investigation Target

Identify what needs investigation:

• Error Investigation: Extract error type, message, and stack trace
• Module Investigation: Identify the module/component to understand
• Question Investigation: Clarify the specific question being asked

Step 2: Launch Parallel Subagents

Spawn explore subagents to investigate different aspects simultaneously (some aspects may and should require multiple subagents):

Core Implementation

• Find the primary source files
• Understand the main logic flow
• Identify key functions/classes

Dependencies & Consumers

• What depends on this code?
• What does this code depend on?
• Map the dependency graph

Test Coverage

• Find all tests for this code
• Identify what scenarios are tested
• Find gaps in test coverage

Error Context (if error investigation)

• Trace the error through the stack
• Find where the bad state originated
• Identify the root cause

Similar Patterns

• Search for similar code elsewhere
• How do other parts handle this?
• Are there established patterns?

Architecture Context

• Read relevant architecture.md files
• Understand design decisions
• Check for documented constraints

External Research (Web Search)

• Search for error messages in external sources
• Look up known issues in libraries/frameworks
• Find documentation for relevant APIs
• Check GitHub issues for similar problems
• Search for Stack Overflow discussions

Step 3: Synthesize Findings

After subagents complete, consolidate into structured findings:

1. Summary: One paragraph overview
2. Root Cause (if error): The actual source of the problem
3. Affected Components: List of files/modules involved
4. Data Flow: How data moves through the system
5. Test Gap Analysis: Why tests didn't catch this
6. Similar Patterns: How similar issues are handled elsewhere
7. External Research: Relevant findings from web search (if applicable)
8. Recommendations: Suggested approaches (NOT implementations)

Step 4: Write Report

Write findings to: temp/investigate/investigation_{topic}_{YYYY-MM-DD_HHMMSS}.md (relative to the current working directory)

Report structure:

# Investigation: {Topic}

**Date:** {YYYY-MM-DD}
**Scope:** {What was investigated}

## Summary
{One paragraph overview}

## Root Cause
{If error investigation - the actual source}

## Affected Components
- {file1}: {role}
- {file2}: {role}

## Data Flow
{How data moves through the system}

## Test Gap Analysis
{Why existing tests didn't catch this}

## Similar Patterns
{How similar scenarios are handled elsewhere}

## External Research
{Relevant findings from web search - library bugs, known issues, documentation insights}
{Include source URLs for reference}

## Recommendations
{Suggested approaches - NOT code changes}

After writing the report file, emit the structured output token as the very last line of your text output:

investigation_path = {absolute_path_to_investigation_report_file}

Subagent Prompt Template

Use this template for each Explore subagent:

Investigate {specific aspect} of {target}.

Focus on:
1. {Specific question 1}
2. {Specific question 2}
3. {Specific question 3}

This is a research task - DO NOT modify any code.
Report your findings in a structured format.