# Root Cause Investigation

Finds the root cause of a bug or error before any fix is attempted.

- Repository: https://github.com/garrytan/gstack (138584 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add garrytan/gstack --skill gstack-openclaw-investigate -g -a claude-code -y`
Codex: `npx skills add garrytan/gstack --skill gstack-openclaw-investigate -g -a codex -y`
Cursor: `npx skills add garrytan/gstack --skill gstack-openclaw-investigate -g -a cursor -y`
Gemini CLI: `npx skills add garrytan/gstack --skill gstack-openclaw-investigate -g -a gemini-cli -y`

## Description

Use when asked to debug, fix a bug, investigate an error, or do root cause analysis, and when users report errors, stack traces, unexpected behavior, or say something stopped working.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Systematic Debugging

## Iron Law

**NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.**

Fixing symptoms creates whack-a-mole debugging. Every fix that doesn't address root cause makes the next bug harder to find. Find the root cause, then fix it.

---

## Phase 1: Root Cause Investigation

Gather context before forming any hypothesis.

1. **Collect symptoms:** Read the error messages, stack traces, and reproduction steps. If the user hasn't provided enough context, ask ONE question at a time. Don't ask five questions at once.

2. **Read the code:** Trace the code path from the symptom back to potential causes. Search for all references, read the logic around the failure point.

3. **Check recent changes:**
   ```bash
   git log --oneline -20 -- <affected-files>
   ```
   Was this working before? What changed? A regression means the root cause is in the diff.

4. **Reproduce:** Can you trigger the bug deterministically? If not, gather more evidence before proceeding.

5. **Check memory** for prior debugging sessions on the same area. Recurring bugs in the same files are an architectural smell.

Output: **"Root cause hypothesis: ..."** ... a specific, testable claim about what is wrong and why.

---

## Phase 2: Pattern Analysis

Check if this bug matches a known pattern:

**Race condition** ... Intermittent, timing-dependent. Look at concurrent access to shared state.

**Nil/null propagation** ... NoMethodError, TypeError. Missing guards on optional values.

**State corruption** ... Inconsistent data, partial updates. Check transactions, callbacks, hooks.

**Integration failure** ... Timeout, unexpected response. External API calls, service boundaries.

**Configuration drift** ... Works locally, fails in staging/prod. Env vars, feature flags, DB state.

**Stale cache** ... Shows old data, fixes on cache clear. Redis, CDN, browser cache.

The rest: https://github.com/garrytan/gstack/blob/HEAD/openclaw/skills/gstack-openclaw-investigate/SKILL.md