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
npx skills add garrytan/gstack --skill gstack-openclaw-investigate -a claude-codeWhat 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-investigateskill: 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-code2Manually: put the files in place
~/.claude/skills/gstack-openclaw-investigate/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/gstack-openclaw-investigate/
1Skills CLI (Vercel)
npx skills add garrytan/gstack --skill gstack-openclaw-investigate -a codex2Manually: put the files in place
.agents/skills/gstack-openclaw-investigate/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add garrytan/gstack --skill gstack-openclaw-investigate -a cursor2Manually: put the files in place
.cursor/skills/gstack-openclaw-investigate/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install garrytan/gstack openclaw/skills/gstack-openclaw-investigate2Manually: put the files in place
.github/skills/gstack-openclaw-investigate/SKILL.md1Skills CLI (Vercel)
npx skills add garrytan/gstack --skill gstack-openclaw-investigate -a gemini-cli2Platform CLI
gemini skills install https://github.com/garrytan/gstack --path openclaw/skills/gstack-openclaw-investigateManually: put the files in place
.devin/skills/gstack-openclaw-investigate/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add garrytan/gstack --skill gstack-openclaw-investigate -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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