Skip to main content
skill CX Codex

gstack-openclaw-investigate — Claude Code skill: how to install

gstack-openclaw-investigate makes the agent find a bug's root cause and confirm it before changing code, then apply a minimal fix with a regression test and write a report.

MIT 302 installs ★ 142,291 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add garrytan/gstack --skill gstack-openclaw-investigate -a claude-code
Open on GitHub

What gstack-openclaw-investigate does

The skill's rule is that nothing gets fixed until the root cause is known. The agent starts from the symptoms: error text, stack trace, reproduction steps, asking one question at a time if something is missing. It then walks the code backward from the failure point and checks recent history with git log --oneline -20 -- <affected-files> to see whether the bug is a regression. This phase ends with a specific hypothesis that can be tested.

Next the hypothesis is matched against common bug types: races, null propagation, corrupted state, broken integrations, config drift between environments, stale caches. A temporary log or assertion confirms it before any fix. After three wrong hypotheses in a row the skill stops and tells you the problem may be architectural. It then offers options: try a new hypothesis, hand it to a human, or add logging and wait for the next occurrence.

The fix itself stays small, with a regression test that fails before the change and passes after it. If more than 5 files are touched, the agent warns you first. At the end it replays the original scenario, runs the tests and saves a dated report to memory/ with status DONE, DONE_WITH_CONCERNS or BLOCKED.

What it helps with

  • trace a crash from a stack trace to its actual cause
  • tell whether a bug is a regression by reading the git history of affected files
  • figure out why code works locally but fails in staging or prod
  • add a regression test that fails without the fix
  • keep a dated debug report in memory/ for later sessions

Example prompts for the agent

  • Use the gstack-openclaw-investigate skill: the build broke after yesterday's commit, here is the log.
  • Find the root cause of this error. Don't change anything until the hypothesis is confirmed.
  • Everything stopped working after the dependency update. Investigate, fix it and add a regression test.

How to install gstack-openclaw-investigate

1Skills CLI (Vercel)

npx skills add garrytan/gstack --skill gstack-openclaw-investigate -a claude-code

2Manually: put the files in place

~/.claude/skills/gstack-openclaw-investigate/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/gstack-openclaw-investigate/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about gstack-openclaw-investigate

How do I install gstack-openclaw-investigate in Claude Code?

Run npx skills add garrytan/gstack --skill gstack-openclaw-investigate -a claude-code. The skill file lives at ~/.claude/skills/gstack-openclaw-investigate/SKILL.md.

What does gstack-openclaw-investigate do?

It makes the agent locate and verify the root cause of a bug before editing code, then apply a minimal fix backed by a regression test. It finishes with a debug report and a status.

What happens when the hypotheses keep failing?

After three failed hypotheses the skill stops and says the issue may be architectural. You choose between a new hypothesis, human review, or adding logging.

Source text

SKILL.md · MIT
---
name: gstack-openclaw-investigate
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.
---

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

Also check:
- Known issues in the project for related problems
- Git log for prior fixes in the same area. Recurring bugs in the same files are an architectural smell, not a coincidence.

**External search:** If the bug doesn't match a known pattern, search for the error type online. **Sanitize first:** strip hostnames, IPs, file paths, SQL, customer data. Search the error category, not the raw message.

---

## Phase 3: Hypothesis Testing

Before writing ANY fix, verify your hypothesis.

1. **Confirm the hypothesis:** Add a temporary log statement, assertion, or debug output at the suspected root cause. Run the reproduction. Does the evidence match?

2. **If the hypothesis is wrong:** Search for the error (sanitize sensitive data first). Return to Phase 1. Gather more evidence. Do not guess.

3. **3-strike rule:** If 3 hypotheses fail, **STOP**. Tell the user:

   "3 hypotheses tested, none match. This may be an architectural issue rather than a simple bug."

   Options:
   - Continue investigating with a new hypothesis (describe it)
   - Escalate for human review (needs someone who knows the system)
   - Add logging and wait (instrument the area and catch it next time)

**Red flags** ... if you see any of these, slow down:
- "Quick fix for now" ... there is no "for now." Fix it right or escalate.
- Proposing a fix before tracing data flow ... you're guessing.
- Each fix reveals a new problem elsewhere ... wrong layer, not wrong code.

---

## Phase 4: Implementation

Once root cause is confirmed:

1. **Fix the root cause, not the symptom.** The smallest change that eliminates the actual problem.

2. **Minimal diff:** Fewest files touched, fewest lines changed. Resist the urge to refactor adjacent code.

3. **Write a regression test** that:
   - **Fails** without the fix (proves the test is meaningful)
   - **Passes** with the fix (proves the fix works)

4. **Run the full test suite.** No regressions allowed.

5. **If the fix touches >5 files:** Flag the blast radius to the user before proceeding. That's large for a bug fix.

---

## Phase 5: Verification & Report

**Fresh verification:** Reproduce the original bug scenario and confirm it's fixed. This is not optional.

Run the test suite.

Output a structured debug report:

**DEBUG REPORT**
- **Symptom:** what the user observed
- **Root cause:** what was actually wrong
- **Fix:** what was changed, with file references
- **Evidence:** test output, reproduction showing fix works
- **Regression test:** location of the new test
- **Related:** prior bugs in same area, architectural notes
- **Status:** DONE | DONE_WITH_CONCERNS | BLOCKED

Save the report to `memory/` with today's date so future sessions can reference it.

---

## Important Rules

- **3+ failed fix attempts: STOP and question the architecture.** Wrong architecture, not failed hypothesis.
- **Never apply a fix you cannot verify.** If you can't reproduce and confirm, don't ship it.
- **Never say "this should fix it."** Verify and prove it. Run the tests.
- **If fix touches >5 files:** Flag to user before proceeding.
- **Completion status:**
  - DONE ... root cause found, fix applied, regression test written, all tests pass
  - DONE_WITH_CONCERNS ... fixed but cannot fully verify (e.g., intermittent bug, requires staging)
  - BLOCKED ... root cause unclear after investigation, escalated

© garrytan · MIT · garrytan/gstack

Similar skills

All skills for Testing and QA →

From the same set26

The whole set →
landing-report landing-report is a Claude Code skill that inspects release version queues across parallel workspaces. Runs read-only checks via the gstack-next-version tool without modifying project files. CX Codex +1 336installs scrape scrape is a Claude Code skill that reads data off a web page through the Aside browser, inside sessions where the sign-in already happened. It fires on asks like "get data from this page". CX Codex +1 335installs gstack-openclaw-office-hours The gstack-openclaw-office-hours skill turns your AI agent into a Y Combinator office hours partner to pressure-test product ideas. It enforces a strict rule against writing code and outputs a design doc. CX Codex +1 327installs document-generate document-generate is a Claude Code skill that creates docs for a feature, module, or whole project. It starts when asked to write or generate documentation. CX Codex +1 319installs gstack-openclaw-ceo-review gstack-openclaw-ceo-review makes the agent review a plan the way a CEO would: question the premise, find weak spots, and decide whether to widen or trim scope. CX Codex +1 318installs gstack-openclaw-retro gstack-openclaw-retro generates weekly engineering retrospectives from git history, analyzing developer sessions, test ratios, churn hotspots, and individual contributions. CX Codex +1 314installs hackernews-frontpage Pulls the Hacker News front page and returns the top 30 stories as JSON with rank, title, link, points and comments. CX Codex +1 311installs diagram diagram is a Claude Code skill that turns an English description or Mermaid source into diagram files. It runs on requests to make, draw, or visualize a diagram. CX Codex +1 266installs

Project sponsors

Companies that keep this analytics open