Investigate

Investigate issues and report findings. Does NOT create plans or modify code.

Purpose

• Investigate reported issues (API errors, wrong data, unexpected behavior)
• Debug deployment or runtime issues using deployment logs
• Analyze codebase to understand behavior
• Examine configuration and environment issues
• Report findings only - user decides next steps

Arguments

$ARGUMENTS should describe what to investigate:

• What happened vs what was expected
• Error messages or unexpected values
• Which environment (if applicable) — if not specified, ask
• Deployment ID if it's a deployment issue
• Any context that helps narrow the scope

Context Gathering

IMPORTANT: Do NOT hardcode MCP names or folder paths. Always read CLAUDE.md to discover:

1. Available MCP servers - Look for "MCP SERVERS", "MCPs", or similar sections to find:

   • Error tracking MCPs for crash/error investigation (use ToolSearch to load tools before calling them)
   • Deployment MCPs for logs and service status (Railway, Vercel, AWS, etc.)
   • Any other configured MCPs

2. Sentry configuration - Look for "SENTRY" section. If present, use the organization, project, and region URL for all Sentry MCP calls. If absent, skip Sentry. See the Sentry Integration section below for detailed guidance.

3. Project structure - Look for "STRUCTURE" or "FOLDER STRUCTURE" sections to understand:

   • Where source code and documents are stored
   • Naming conventions and organization

4. Domain concepts - Look for sections describing:

   • Data schemas and formats
   • Business rules and validation
   • API endpoints and their behavior

5. Environments - Look for "ENVIRONMENTS" section to discover:

   • Environment names (production, staging, etc.)
   • Associated branches and URLs
   • Deployment service configurations

Sentry Integration

Conditional: Only applies if CLAUDE.md has a SENTRY section. If no Sentry is configured, skip this entirely.

Read CLAUDE.md SENTRY section for organizationSlug, projectSlugOrId, and regionUrl. Always pass these to every Sentry MCP call. Use ToolSearch to load Sentry tools before calling them.

When to use Sentry

• User reports crashes or errors in production
• Investigating runtime exceptions or unhandled errors
• Need crash frequency, affected user count, or error trends
• User provides a Sentry issue URL or issue ID
• Need production stack traces

Which Sentry tool to use

Investigation patterns

Error investigation:

1. search_issues — find matching issues by description or symptoms
2. get_issue_details — get stacktrace, affected users, frequency
3. get_issue_tag_values — check environment/release/url distribution
4. search_issue_events — filter to specific timeframe or environment
5. analyze_issue_with_seer — get AI root cause analysis with code fixes

Performance investigation:

1. search_events — query spans: "slow API requests", "p95 response time"
2. get_trace_details — inspect a specific trace for bottlenecks

Trend investigation:

1. search_events — "count of errors today vs yesterday", "error rate this week"
2. search_issues — "new issues in the last 24 hours"

Tips

• Start with search_issues for broad exploration, get_issue_details when you have a specific issue
• Use search_events for "how many errors today?" style questions
• Cross-reference Sentry stack traces with local codebase to identify the exact code path
• Check tag distributions (device, OS, release, environment) to understand issue scope

Investigation Workflow

Step 1: Classify the Investigation Type

Based on $ARGUMENTS, determine what you're investigating:

Step 2: Gather Evidence

For Sentry (if configured): Start with Sentry for error/performance investigations — it provides the richest context (stacktraces, traces, frequency, affected environments). See the Sentry Integration section above for tool selection and patterns.

For Codebase Analysis:

• Use Grep/Glob for specific searches
• Use Task tool with subagent_type=Explore for broader exploration
• Read relevant source files, configs, and tests

For Deployment Issues (if MCP available):

1. Determine target environment from $ARGUMENTS (consult CLAUDE.md's ENVIRONMENTS section). If unclear, ask user.
2. Check deployment MCP status
3. List services to find affected service
4. List recent deployments with statuses — pass environment: "<target>" explicitly if the MCP supports it
5. Get deployment and build logs — pass environment: "<target>" explicitly if the MCP supports it
6. Search logs for errors using filters (e.g., @level:error) if the MCP supports it

For API Issues:

• Trace the request flow through the codebase
• Check route handlers, middleware, and data access layers
• Look for error handling gaps
• Check environment variable usage

For Data Issues:

• Examine data models and schemas
• Check validation logic
• Trace data flow from input to storage
• Look for transformation errors

Step 3: Form Conclusions

After gathering evidence, determine:

1. Root Cause Identified - You found what's causing the issue
2. Root Cause Suspected - Strong hypothesis but not 100% certain
3. Multiple Possibilities - Several potential causes, need more info
4. Nothing Wrong Found - Investigation shows system working correctly
5. Cannot Determine - Insufficient information to conclude

Investigation Report Format

Write findings to the conversation (NOT to a file):

## Investigation Report

**Subject:** [What was investigated]
**Environment:** [production | staging | codebase-only]
**Conclusion:** [Root Cause Identified | Suspected | Multiple Possibilities | Nothing Wrong | Cannot Determine]

### Context
- **MCPs used:** [list MCPs accessed]
- **Sentry issues reviewed:** [issue IDs if applicable]
- **Environment queried:** [production | staging | N/A]
- **Files examined:** [list key files checked]
- **Logs reviewed:** [deployment IDs, time ranges if applicable]

### Evidence
[What you found - be specific with data points, log excerpts, file contents]

### Findings

[Explain what you discovered. If root cause found, explain it clearly.
If nothing wrong, explain what was checked and why it appears correct.
If uncertain, list possibilities ranked by likelihood.]

### Recommendations (Optional)
[Only if you have specific suggestions - do NOT write a fix plan]

Deployment Debugging Guidelines

When investigating deployment issues (if MCP available):

1. Identify target environment - Determine environment name from CLAUDE.md's ENVIRONMENTS section
2. Check status first - Verify MCP access
3. List recent deployments - Get deployment IDs and statuses (pass environment param if supported)
4. Get targeted logs - Search for errors using filters (pass environment param if supported)
5. Look for patterns - Repeated errors, timing correlations
6. Check configuration - Environment variables, settings (pass environment param if supported)

Error Handling

Rules

• Report only - Do NOT modify source code or files
• No plans - Do NOT write PLANS.md or fix plans
• Start with Sentry - For error/performance investigations, check Sentry before deployment logs (if configured)
• Sentry constants - ALWAYS pass organizationSlug, projectSlugOrId, and regionUrl from CLAUDE.md to Sentry tools
• Discover MCPs - Read CLAUDE.md to find available tools
• Explicit environment - ALWAYS pass the environment parameter to deployment MCP tools when supported; never rely on CLI defaults
• Be thorough - Check multiple sources before concluding
• Be specific - Include exact values, line numbers, timestamps
• Be honest - If uncertain, say so; if nothing wrong, say so

What NOT to Do

1. Don't create PLANS.md - This skill only reports
2. Don't modify code - Investigation is read-only
3. Don't assume MCPs - Discover from CLAUDE.md
4. Don't conclude prematurely - Gather sufficient evidence first
5. Don't force findings - "Nothing wrong" is a valid conclusion

Termination

When you finish investigating, output the investigation report.

If bugs or issues were found that need fixing, end with:

---
Investigation complete. Issues found that may need fixing.

Would you like me to create a fix plan? Say 'yes' or run `/plan-fix` with the context above.
(Fix plans will create Linear issues with your project's issue prefix in Todo state)

If nothing wrong was found or no fix needed, end with:

---
Investigation complete.

To take action based on these findings:
- For bug fixes: Use `plan-fix` with this context (creates Linear issues in Todo)
- For feature changes: Use `plan-inline` with specific request (creates Linear issues in Todo)
- For further investigation: Provide more details and run investigate again

Do not offer to implement fixes directly. Report findings and offer skill chaining if appropriate.