regression-root-cause-analyzer

name	regression-root-cause-analyzer
description	Traces regressions to the specific commit, change, or code path that introduced the behavioral breakage. Use when a previously passing test or feature now fails, when the user asks what change caused a regression, or when bisecting a regression across commits.
license	Apache-2.0
metadata	{"category":"debugging","suite":"general-secure-coding-agent-skills","version":"0.3.0","related":"bug-localization, szz-bug-identifier, bug-to-patch-generator"}

Regression Root Cause Analyzer

A regression has one advantage over a greenfield bug: somewhere in history there is a commit where it worked. The entire skill is exploiting that advantage. Do not read code first — read history first.

Step 1 — Establish the good/bad bounds

What you know	Good bound	Bad bound
"Worked in v2.3, broken in v2.4"	v2.3 tag	v2.4 tag
"Broke sometime this week"	Monday's first commit	HEAD
"Test X just started failing in CI"	Last green CI SHA	First red CI SHA
"Broke after I pulled"	ORIG_HEAD or reflog	HEAD
"No idea when"	Oldest tag — or bail (§ edge cases)	HEAD

Verify both bounds before bisecting. Check out good → run → confirm green. Check out bad → run → confirm red. If either bound is wrong, bisect will converge on garbage.

Step 2 — Bisect

git bisect is log₂(N), so even 1000 commits is 10 runs. Automate if the oracle is scriptable:

git bisect start <bad> <good>
git bisect run ./oracle.sh

Where oracle.sh exits 0 when the regression is absent and non-zero when present. If the oracle is manual (visual check), you're doing it by hand — still only ~10 iterations.

Oracle situation	Approach
Single failing test	oracle.sh = pytest path/to/test.py::test_name
Build breaks mid-range	Exit 125 in oracle to skip — bisect knows how to route around
Oracle takes 10 minutes	Bisect by first-parent on merge commits first, then drill into the guilty merge
Behavior, not a test	Write a one-liner test now; it's your bisect oracle and your regression guard

Step 3 — Read the guilty commit

Bisect gives you a SHA. Now engage: git show <sha>. You're looking for which hunk caused it, not just which commit.

Commit shape	Triage
Single small hunk	Done — this is the root cause
Multi-file refactor	Revert one file at a time against bad; re-run oracle
Merge commit	Bisect the merged branch separately: git bisect start <merge> <merge>^1
Dependency bump	Diff the dep's changelog between old/new pins
Seemingly unrelated commit	Re-verify your bounds — 90% of "bisect lied" is actually bad bounds

Worked example

Input: test_admin_can_delete_user passes on v3.1.0, fails on main (400 commits later).

git bisect start main v3.1.0
git bisect run pytest tests/test_admin.py::test_admin_can_delete_user -x

9 iterations. Guilty: a3f91c2 — Refactor permission middleware.

git show a3f91c2 — 200-line diff across 4 files. Revert files one at a time:

git checkout a3f91c2 -- src/middleware/perms.py && pytest ... -x   # still red
git checkout a3f91c2^ -- src/middleware/perms.py && pytest ... -x  # green

Fault is in perms.py. Inspect its hunk: ADMIN in user.roles became user.role == ADMIN during the refactor — but users have a list of roles. One-character design shift, 200-line diff.

→ bug-to-patch-generator with fault location src/middleware/perms.py:L42.

Edge cases

• Bisect blames a merge commit and both parents are green: The bug is in the merge itself — an automatic or manual merge resolution that combined two correct changes into an incorrect result. Inspect git show -m <merge>.
• The commit reverts cleanly but the test still fails: Your bounds were wrong, or there are two independent regressions. Bisect again from good to the commit before the one you found.
• Good bound doesn't build anymore (toolchain drift): Use git bisect skip generously, or bisect the generated artifact (if CI retains old builds) rather than source.
• No known good bound: This isn't a regression — it's a bug that was always there. → bug-localization.

Do not

• Do not start by reading diffs manually. Bisect is faster than you are.
• Do not trust a bisect whose good bound you haven't verified. Garbage in, garbage out.
• Do not stop at "this commit." The output is "this line in this commit" — keep drilling.
• Do not blame the dependency bump without reading the dep's changelog. The bump surfaced the bug; it might not have caused it.

Output format

## Introducing commit
<sha> — <subject>
<author>, <date>

## Fault hunk
<file:line-range>
<the relevant diff lines, not the whole commit>

## Mechanism
<One paragraph: what the change did and why it breaks the observed behavior>

## Handoff
→ bug-to-patch-generator with <file>:<line>