菜单
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.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Generates code comments that explain non-obvious intent, constraints, and tradeoffs — not what the code already says. Use when code is correct but opaque, when documenting for future maintainers, or when a function's why is harder to see than its what.
Identifies recurring structural patterns in a codebase — idioms, copy-paste clones, homegrown abstractions — and characterizes each as a reusable template. Use when learning a codebase's conventions, when hunting for copy-paste that should be a function, or when documenting how this team does things.
Finds code by meaning, structure, or text across large codebases — picks the right search strategy (grep, AST query, call graph walk, semantic search) for the question being asked. Use when the user asks where something is implemented, when navigating unfamiliar code, or when a simple grep isn't enough.
Produces natural-language summaries of what code does at the function, class, module, or subsystem level, with length and abstraction scaled to the scope. Explains purpose, side effects, and non-obvious behavior rather than restating syntax. Use when onboarding to unfamiliar code, when the user asks what something does, when generating docstrings or architecture notes, or when preparing a handoff document.
Translates a single function or small code unit between programming languages, mapping idioms and preserving observable behavior. Use when porting one function, when the user pastes code and asks for it in another language, or as the per-unit primitive for larger migrations.
Identifies natural component boundaries inside a monolith by clustering the dependency graph, finding the cuts with minimum coupling. Use when planning to modularize or extract microservices, when deciding what can be deployed independently, or when the user asks where the seams in this codebase are.
| 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"} |
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.
| 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.
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 |
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 |
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.
git show -m <merge>.git bisect skip generously, or bisect the generated artifact (if CI retains old builds) rather than source.bug-localization.## 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>