gstack-investigate

Investigate: root cause before any fix

Start here, before reading code. In the repository (cd into it first: the shell starts in the workspace root), run with execute, adding the failing file or directory if you know it:

git status --short
git log --oneline -20 -- <path>

Then reproduce the symptom with the project's own test or run command, and write down what you saw, before you form a hypothesis.

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.

How to work

Find the root cause, fix it with the smallest change, prove the fix, and finish with the DEBUG REPORT below. The order, tools and depth are yours. Three lessons that cost real time before:

• Before calling two queries, helpers or code paths duplicates, read their call sites: what looks identical usually differs in a caller's guard, transaction or scope, and the "duplicate" is the one that is right.
• Before timing anything that spawns git in a benchmark or bisect worktree, run git update-index --refresh there: a stale index makes the first git status/git diff pay a full refresh and the measurement lies.
• Two fixes that shared one premise failed the same gate — write the premise down in one sentence and test it before a third fix. The evidence already points away from it.

Three guards:

• 3-strike rule: if 3 hypotheses fail, STOP and ask the user: A) continue with a new hypothesis (describe it), B) escalate for human review, C) add logging and wait.
• Blast radius: if the fix touches more than 5 files, ask the user: A) proceed, the root cause spans these files, B) split, fixing the critical path now, C) rethink for a more targeted approach.
• Web searches: search the generic error class, library and version, never the raw error text, hostnames, IPs, file paths, SQL, customer data or secrets.