Investigate

What Is This?

Overview

The Investigate skill brings a structured, four-phase debugging methodology to your development workflow. Rather than applying quick fixes that mask underlying problems, this skill enforces a disciplined approach: investigate the symptoms, analyze the evidence, hypothesize the root cause, and only then implement a solution. This sequence prevents the common trap of treating symptoms while leaving the actual defect untouched.

At the core of this skill is what practitioners call the Iron Law: no fix is applied without first identifying the root cause. This constraint sounds simple, but it fundamentally changes how developers interact with broken systems. Instead of reaching for the nearest plausible patch, the workflow demands evidence before action. The result is fewer regressions, cleaner codebases, and a documented trail of reasoning that benefits the entire team.

The skill activates automatically when you describe errors, unexpected behavior, or broken functionality. Whether you say "debug this," "fix this bug," "why is this broken," or "root cause analysis," the Investigate skill engages its structured process. It also surfaces proactively when the context suggests troubleshooting is needed, even if you have not explicitly requested it.

Who Should Use This

• Backend engineers dealing with intermittent failures, service crashes, or data corruption that resist obvious explanations
• Frontend developers tracking down rendering bugs, state inconsistencies, or network request failures that appear only under specific conditions
• DevOps and platform engineers diagnosing infrastructure issues, deployment failures, or performance degradation in production environments
• QA engineers performing root cause analysis on reported defects before escalating to development teams

Why Use It?

Problems It Solves

• Recurring bugs: Without root cause identification, the same defect reappears after each superficial fix, wasting repeated engineering time
• Regression risk: Patches applied without understanding the system can break adjacent functionality in ways that are difficult to trace
• Knowledge loss: Unstructured debugging produces no record of what was tried, what was found, or why a particular fix was chosen
• Wasted debugging time: Jumping to solutions before gathering evidence often leads investigators down incorrect paths for extended periods

Core Highlights

• Four-phase methodology: investigate, analyze, hypothesize, implement
• Iron Law enforcement prevents premature fixes
• Works with the Bash tool for direct system and log inspection
• Proactive activation when error context is detected
• Structured output that doubles as debugging documentation
• Applicable to code bugs, infrastructure failures, and unexpected behavior
• Reduces regression rates by requiring evidence-based solutions
• Compatible with any language or technology stack

How to Use It?

Basic Usage

Trigger the skill by describing the problem in natural language. The skill then guides you through each phase using available tools.

## Phase 1:

Investigate - gather raw evidence
cat /var/log/app/error.log | grep "ERROR" | tail -50
journalctl -u myservice --since "1 hour ago"

## Phase 2:

Analyze - examine the application state
ps aux | grep node
netstat -tlnp | grep 3000

## Phase 3:

Hypothesize - test a specific theory
curl -v http://localhost:3000/health
env | grep DATABASE_URL

Specific Scenarios

Scenario 1: Service fails to start after deployment Begin by checking exit codes and startup logs before touching any configuration. Use systemctl status myservice and journalctl -xe to collect the actual failure message before forming any hypothesis.

Scenario 2: API endpoint returns unexpected 500 errors Reproduce the error with a controlled request, capture the full stack trace, then trace the execution path through logs before modifying any handler code.

Real-World Examples

A database connection pool exhaustion issue might look like a memory leak until log timestamps reveal that connections are never released after a specific query pattern. The investigation phase surfaces this before any memory-related fix is attempted.

A deployment failure attributed to a missing environment variable is confirmed only after checking the actual runtime environment, not the deployment script, where the variable was correctly defined but overridden downstream.

When to Use It?

Use Cases

• Debugging application crashes or unhandled exceptions in production
• Investigating why a previously passing test suite now fails
• Tracing the origin of data corruption or unexpected state changes
• Diagnosing slow queries or performance regressions after a code change
• Analyzing why a scheduled job stopped executing
• Identifying the cause of intermittent network or timeout errors
• Performing postmortem analysis after an incident

Important Notes

Requirements

• Bash tool access is required for system-level investigation commands
• Sufficient log verbosity must be configured in the target application to provide meaningful evidence
• Reproducible conditions for the bug improve investigation accuracy significantly
• Access to the relevant environment, whether local, staging, or production, is necessary for accurate diagnosis