investigate

Guide four-phase root-cause investigation of bugs before implementing fixes.

Updated Aug 27, 2026
One-click install
npx skills add https://github.com/gfires/motion-analysis --skill investigate-gfires
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: investigate
Source: https://github.com/gfires/motion-analysis/tree/main/investigate
Command: npx skills add https://github.com/gfires/motion-analysis --skill investigate-gfires

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Systematic debugging with root cause investigation. Four phases: investigate, analyze, hypothesize, implement. Iron Law: no fixes without root cause. Use when asked to "debug this", "fix this bug", "why is this broken", "investigate this error", or "root cause analysis". Proactively invoke this skill (do NOT debug directly) when the user reports errors, 500 errors, stack traces, unexpected behavior, "it was working yesterday", or is troubleshooting why something stopped working. (gstack)

Core Features & Use Cases

  • Root-cause investigation: A disciplined process to identify the underlying cause of bugs before applying fixes.
  • Phase-driven workflow: Four phases guide symptoms to solutions, reducing churn and rework.
  • Reproduction & validation: Collect evidence, reproduce the issue, test hypotheses, and confirm root cause.

Quick Start

Describe the bug, gather steps to reproduce, and start the four-phase investigate workflow.

Frequently Asked Questions about investigate

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I find the root cause of a bug instead of just patching the symptoms?

To find the root cause of a bug, follow a four-phase investigation workflow: investigate, analyze, hypothesize, and implement. This systematic approach enforces evidence gathering and reproduction to confirm the underlying issue before applying any fixes.

What is the best way to debug a 500 error or unexpected stack trace?

The best way to debug a 500 error or stack trace is to proactively trigger a root-cause investigation workflow. This process collects evidence, searches the codebase, and tests hypotheses to validate the exact trigger before modifying code.

Why should I use a structured workflow to investigate a performance regression?

Using a structured workflow to investigate a performance regression prevents jumping to premature fixes. It guides you through gathering data, reproducing the issue, and testing hypotheses, which reduces churn and confirms the true root cause.

Can I debug unexpected behavior by asking for clarifications during the investigation?

Yes, you can debug unexpected behavior by gathering clarifications interactively. The investigation workflow leverages user interactions alongside code search and data collection to build accurate reproduction steps and validate hypotheses.

When do I need a root-cause analysis for troubleshooting broken code?

You need a root-cause analysis for troubleshooting broken code whenever you encounter errors, stack traces, unexpected behavior, or regressions. It ensures you gather sufficient evidence and test hypotheses before implementing a fix.