regression-hunt
/regression-hunt
Find the commit that introduced a regression by bisecting history in an isolated worktree. Use when a test, build, or behavior used to pass and now fails, when the user asks when something broke, which commit broke it, or asks to bisect. Requires a command that exits 0 on a healthy commit and non-zero on a broken one.
- Author
- vezeqs ↗
- Repository
- git-forensics ↗
- Licence
- MIT
- Last repository change
- 31.10.2026
Assessment and security
- Files in this package
- 3
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 31.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/hunt.py
What it does and when to use it
Find the commit that introduced a regression by bisecting history in an isolated worktree. Use when a test, build, or behavior used to pass and now fails, when the user asks when something broke, which commit broke it, or asks to bisect. Requires a command that exits 0 on a healthy commit and non-zero on a broken one.
Original author description
Find the commit that introduced a regression by bisecting history in an isolated worktree. Use when a test, build, or behavior used to pass and now fails, when the user asks when something broke, which commit broke it, or asks to bisect. Requires a command that exits 0 on a healthy commit and non-zero on a broken one.
How it works
- When to use
- Inputs you must establish
- Run it
- Exit codes
- Reporting the result
- Rules
- Limits
SKILL.md preview
--- name: regression-hunt description: Find the commit that introduced a regression by bisecting history in an isolated worktree. Use when a test, build, or behavior used to pass and now fails, when the user asks when something broke, which commit broke it, or asks to bisect. Requires a command that exits 0 on a healthy commit and non-zero on a broken one. license: MIT metadata: version: "1.0.0" author: vezeqs --- # Regression hunt Answer one question with evidence: **which commit introduced this failure?** The bisect runs in a throwaway worktree. The user's working tree, index, and branch are never touched, so an interrupted run cannot lose their work. ## When to use - A test, build, typecheck, or runtime behavior used to pass and now fails. - The user says "when did this break", "find the breaking commit", "bisect this", or "which change caused it". - The failure is deterministic: the same command gives the same answer on the same commit. Do not use it when: - The failure is flaky. Bisect assumes a stable answer per commit; a flaky command produces a confident, wrong commit. Stabilize or quarantine the test first, then bisect. - The command fails at every commit in the range. That is a broken environment, not a regression. The preflight will refuse; do not override it. - The user wants to know *why* a line exists. Use `blame-archaeology`. ## Inputs you must establish 1. **A good revision.** A tag, branch, or SHA where the command passes. 2. **A bad revision.** Defaults to `HEAD`. 3. **A command.** Exit 0 means healthy, non-zero means broken. If the user cannot name a good revision, help them find one from release tags, CI history, or the last known working deployment. Do not guess a SHA and do not pick one because it looks old. A wrong endpoint silently produces a wrong answer. If the user gives you a command that reports "all tests passed" style output, make sure its exit code is meaningful. `pytest -q` is fine; `pytest -q | tail` is not, because the pipeline's exit status is `tail`'s. ## Run it ```sh python3 scripts/hunt.py \ --good v1.4.0 \ --bad HEAD \ --cmd "pytest -q tests/test_parser.py" ``` Paths are relative to this skill's directory. Add `--repo /path/to/checkout` when the working directory is elsewhere. Useful flags: | Flag | Use | | --- | --- | | `--timeout 900` | Slow builds. A timeout is treated as a skip, not as evidence. | | `--json` | Machine-readable report, for pasting into an issue. | | `--keep` | Keep the worktree so the user can inspect the failing state. | | `--no-preflight` | Only when the user explicitly asks to skip the endpoint checks. | For the JSON schema and exit-code contract, read [references/report-format.md](references/report-format.md). ## Exit codes | Code | Meaning | What to do | | --- | --- | --- | | 0 | First bad commit found | Report it with its evidence. | | 2 | No verdict: every probe skipped, or nothing failed in the range | Say so plainly. Do not invent a culprit. | | 3 | Interrupted | The worktree was removed. Nothing to clean up. | | 4 | Usage or preflight failure | Read the message, fix the input, rerun. | ## Reporting the result Lead with the commit, then the evidence, then the limit of the claim: ``` Regression introduced in 23ff297 "break the value" (Test, 2026-10-30). The bisect ran 3 probes between v1.4.0 and HEAD; 23ff297 was the first commit where `pytest -q tests/test_parser.py` failed. Files changed: value.txt (+1 -1). This identifies the change, not the cause. The diff is the next thing to read. ``` Rules for the report: - Quote the full SHA and the subject verbatim. - State the command and the endpoints. A bisect without its command is not reproducible. - Say "this commit introduced the failure", not "this commit is the bug". A commit can expose a latent bug elsewhere. - If exit code was 2, say the range contained no failing commit and stop. - If the user asked why it broke, read the diff and the commit message before offering a mechanism. Do not infer a cause from the commit subject alone. ## Rules - Never run `git bisect` directly in the user's checkout. That mutates their tree and leaves the repository in a bisecting state if it fails. - Never pass `--force` to get past a preflight failure unless the user has explicitly asked to bisect a range you warned them about. - Do not remove the worktree or prune worktrees by hand. The script removes what it created, including on error and on Ctrl-C. - A probe may write into the worktree. Tracked files are restored after each run, so a build step is fine. Untracked files that collide with a commit in range can still block a checkout; if that happens, report it instead of forcing. - Do not run this on a shallow clone without saying so. The range may be incomplete and the answer will look authoritative while being wrong. ## Limits - Merge-heavy histories can produce a commit that is not on the first-parent path. Read the reported parents before blaming a person. - Submodules are not initialized in the worktree. A command that needs them fails at both endpoints, so the preflight refuses the range. Initialize them inside a kept worktree if the user needs the answer. - The worktree lives in the system temp directory. If `/tmp` is small and the build is large, point `TMPDIR` at a bigger volume.
Files in this package (3)
- SKILL.md 5 KB
- references/report-format.md 2 KB
- scripts/hunt.py 18 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · vezeqs/git-forensics | 100 | MIT |
| stella/folio | 90 | Apache-2.0 |
| stella/stella | 90 | Apache-2.0 |
| trailofbits/skills | 90 | CC-BY-SA-4.0 |
Database snapshot: 13.11.2026 · package version 80fde73b9e7e (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100bisect-anything
Find the exact commit (or dependency version, config value, or input) that caused a regression by turning it into an automatic pass/fail check and running git bisect run in a separate worktree, then shrink the bad commit to the hunk that matters and explain it. Handles failing… - 100git-bisect-regression
Find which commit introduced a bug or behavior change using `git bisect`. Use this whenever the user says something "used to work", "worked last week", "stopped working", "broke at some point", asks "which commit broke this", "when did this start", "find the regression" or "who… - 100bisect
Bisect a ClickHouse regression using pre-built master binaries from CI. Use when the user wants to find the commit that introduced a bug. - 100regression-bisecting
Use when a bug was recently introduced but you don't know which commit caused it. - 90git-bisect
Find the exact commit that introduced a regression by driving git bisect with an automated pass/fail script. Use when a behavior worked in an older build and you need the first bad commit out of hundreds, not a guess. - 100bisect
Use when hunting a regression, phrases like "bisect", "find the commit that broke X", "this used to work", "regression in test Y", "when did <symptom> start". Also use when escalated from ci-debug-loop because log analysis can't pinpoint the offending change, or when a…