Menu
Deep investigation of bugs, performance issues, or unexpected behavior
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Build the project (auto-detects build system)
Find and remove dead code, unused imports, and technical debt
Create git commits in logical groups for all current changes
Create a git commit with conventional commit message
Pick up unfinished work from where the last session left off
Debug and fix failing tests or errors
| name | investigate |
| description | Deep investigation of bugs, performance issues, or unexpected behavior |
| argument-hint | <issue-to-investigate> |
Thorough investigation of issues with root cause analysis and recommendations.
OUTPUT: Detailed report with findings, root cause, and recommendations.
$ARGUMENTS - Issue description, error message, or area to investigateLaunch two parallel agents immediately. Both can work simultaneously since forming hypotheses from the issue description is independent from gathering raw data.
Agent 1 - Hypotheses Formation:
Analyze the issue description:
$ARGUMENTSForm 3-5 ranked hypotheses about what might be causing this issue. For each hypothesis, state:
- The suspected cause
- Why this is plausible given the symptoms
- What evidence would confirm or refute it
Return a numbered list of hypotheses with supporting reasoning.
Agent 2 - Data Gathering:
Gather all available data about:
$ARGUMENTSCollect in parallel where possible:
- Error messages and stack traces (search logs, output files, CI artifacts)
- Recent changes to affected areas (
git log --oneline -30 -- path/to/affected/)- Related issues or discussions (search issue trackers if available)
- Current state of affected code paths (read the relevant source files)
- Environment and configuration state
Return all raw findings organized by category.
Wait for both agents to complete. Combine their outputs to form the investigation plan for Phase 2.
Launch four parallel agents, one per evidence dimension. These are completely independent investigations that share no dependencies.
Agent 1 - Code Analysis:
Investigate the code paths related to:
$ARGUMENTSUsing the hypotheses: [insert hypotheses from Phase 1]
Analyze:
- All code paths involved in the issue (read source files, trace call chains)
- Recent changes to affected areas (
git log -p --since="2 weeks ago" -- path/to/affected/)- Dependencies and their versions
- Integration points between components
- Any relevant design patterns or architectural decisions that could contribute
For each hypothesis, note which code evidence supports or contradicts it. Return detailed code-level findings with exact file paths and line numbers.
Agent 2 - Log and Error Analysis:
Analyze logs and error output related to:
$ARGUMENTSSearch for:
- Error patterns matching the reported symptoms (use Grep across log files)
- Timestamp correlations (what happened before, during, and after the error)
- Frequency and distribution of errors
- Stack traces and their common frames
- Warning messages that might indicate preconditions
Return a timeline of events and all error patterns found, with file locations.
Agent 3 - Test Behavior:
Investigate test behavior related to:
$ARGUMENTSPerform:
- Run existing tests for affected areas and capture results
- Write a minimal exploratory test that attempts to reproduce the issue
- Check test coverage of the affected code paths
- Look for flaky tests or tests with known issues in the affected area
- Try to create the smallest possible reproduction case
Return test results, reproduction status, and any newly written test code.
Agent 4 - External Factors:
Investigate external factors related to:
$ARGUMENTSCheck:
- Database state and schema (if applicable)
- Third-party service status and API changes
- Configuration differences between working and broken environments
- Environment variables and their values
- Infrastructure or platform changes (OS updates, dependency updates, CI changes)
- Network conditions or connectivity issues
Return all external factor findings, noting which factors changed recently.
Wait for all four agents to complete. Merge all evidence into a unified evidence set.
Launch one parallel agent per hypothesis from Phase 1. Each agent independently evaluates a single hypothesis against the full evidence set from Phase 2.
For each hypothesis, launch an agent:
Evaluate hypothesis: "[Hypothesis N description]"
Against collected evidence: [Insert merged evidence from Phase 2]
Perform:
- List all evidence that supports this hypothesis
- List all evidence that contradicts this hypothesis
- Attempt to definitively prove or disprove it (run targeted commands, read specific code, write a focused test)
- If the code path can be traced, follow it from entry point through data transformations, decision points, to exit/error point
- Rate confidence: HIGH / MEDIUM / LOW with justification
Distinguish between:
- Proximate cause: The immediate trigger
- Root cause: The underlying issue
- Contributing factors: Things that made it worse
Return: verdict (confirmed/refuted/inconclusive), confidence level, all supporting evidence, and the causal chain if confirmed.
Wait for all hypothesis agents to complete. Select the hypothesis with the strongest evidence as the root cause. If multiple hypotheses are confirmed, determine whether they are independent issues or parts of the same causal chain.
Launch two parallel agents. The report structure and the recommendations are independent deliverables that draw from the same evidence.
Agent 1 - Investigation Report:
Write a complete investigation report for:
$ARGUMENTSUsing root cause: [insert root cause from Phase 3] Using evidence: [insert evidence from Phase 2] Using hypothesis results: [insert results from Phase 3]
Format:
# Investigation Report: [Issue Title] **Date:** [date] **Investigator:** Claude Code **Status:** Complete ## Summary [One paragraph summary of the issue and root cause] ## Problem Statement [What was reported/observed] ## Investigation Steps ### Step 1: [What was checked] **Finding:** [What was discovered] ### Step 2: [What was checked] **Finding:** [What was discovered] ... ## Root Cause [Detailed explanation of the root cause, distinguishing proximate cause, root cause, and contributing factors] ## Evidence - [Evidence 1 with file:line references] - [Evidence 2 with file:line references] ## Contributing Factors - [Factor 1] - [Factor 2] ## Appendix ### Code References - `file1.kt:123` - [description] - `file2.kt:456` - [description] ### Timeline - [timestamp] - [event] - [timestamp] - [event]
Agent 2 - Recommendations and Prevention:
Based on root cause: [insert root cause from Phase 3] And evidence: [insert evidence from Phase 2]
Produce two deliverables:
1. Prioritized Actions:
- Critical - Must do immediately to resolve the issue
- Important - Should do soon to prevent recurrence
- Nice to have - Consider for future resilience
For each action, include specific code changes, file paths, and implementation details.
2. Prevention Plan:
- Testing improvements (specific tests to add, coverage gaps to fill)
- Monitoring and alerting (what metrics to watch, what thresholds to set)
- Code review focus areas (patterns to watch for in future reviews)
- Documentation updates (what to document, where)
Return both deliverables with concrete, actionable items.
Wait for both agents to complete. Merge the recommendations into the report under a ## Recommendations section.
These techniques may be used by any agent during any phase:
git bisect start
git bisect bad HEAD
git bisect good <known-good-commit>
# Test each commit until culprit found
Create the smallest possible test case that reproduces the issue. Prefer an automated test over manual steps.
Diff configurations, code versions, and environments between working and broken states.
IMPORTANT: If any tests fail during investigation, they must be fixed. There is no such thing as a "pre-existing" test failure - all test failures must be resolved before the task is considered complete. The task always completes with completely passing tests.