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 Railway 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
•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:

•
Available MCP servers - Look for "MCP SERVERS" section to find:
- •Deployment MCPs for logs and service status (Railway)
- •Any other configured MCPs
•
Project structure - Look for "STRUCTURE" or "FOLDER STRUCTURE" sections to understand:
- •Where source code and documents are stored
- •Naming conventions and organization
•
Domain concepts - Look for sections describing:
- •Data schemas and formats
- •Business rules and validation
- •API endpoints and their behavior

Investigation Workflow

Step 1: Classify the Investigation Type

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

Category	Indicators	Primary Tools
API	Wrong response, missing data, error codes	Codebase, Railway logs
Deployment	Service down, build failures, runtime errors	Railway MCP
Data	Wrong values, missing records, unexpected state	Codebase, Database queries
Performance	Slow responses, timeouts, resource issues	Railway logs, Codebase
Auth	Login failures, permission errors, token issues	Codebase, Railway logs
General	Unknown cause, need exploration	All available tools

Step 2: Gather Evidence

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 (via Railway MCP):

•Check Railway MCP status
•List services to find affected service
•List recent deployments with statuses
•Get deployment and build logs
•Search logs for errors using filters (e.g., @level:error)

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:

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

Investigation Report Format

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

code

## Investigation Report

**Subject:** [What was investigated]
**Conclusion:** [Root Cause Identified | Suspected | Multiple Possibilities | Nothing Wrong | Cannot Determine]

### Context
- **MCPs used:** [list MCPs accessed]
- **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 (via Railway MCP):

•Check status first - Verify MCP access
•List recent deployments - Get deployment IDs and statuses
•Get targeted logs - Search for errors using filters
•Look for patterns - Repeated errors, timing correlations
•Check configuration - Environment variables, settings

Error Handling

Situation	Action
$ARGUMENTS is vague	Ask for more specific details
CLAUDE.md doesn't exist	Continue with codebase-only investigation
MCP not available	Skip that MCP, note in report what couldn't be checked
File/resource not found	Document in report (may be relevant)
Cannot reproduce issue	Document steps taken, request more context
Logs unavailable	Note in report, suggest alternative approaches

Rules

•Report only - Do NOT modify source code or files
•No plans - Do NOT write PLANS.md or fix plans
•Discover MCPs - Read CLAUDE.md to find available tools
•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

•Don't create PLANS.md - This skill only reports
•Don't modify code - Investigation is read-only
•Don't assume MCPs - Discover from CLAUDE.md
•Don't conclude prematurely - Gather sufficient evidence first
•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:

code

---
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 FOO- prefix in Todo state)

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

code

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