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.