Bisect
Skill tokyubevoxelverse/bisect
Claude Code skill that finds the exact commit that broke it — describe the bug in plain English and it writes the check, drives git bisect in an isolated worktree, and explains why the guilty commit is guilty. 🎯
npx -y skills add tokyubevoxelverse/bisectAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- 14 days oldThe repository was created 14 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Find the exact commit that introduced a bug or regression using automated git bisect. Use when something used to work and doesn't anymore, and the user wants the guilty commit — especially from a plain-English symptom like "scrolling got janky sometime last month."
SKILL.md
3.1 KB, as published. Nobody here has run it
Bisect
Something used to work. Your job is to hand back the exact commit that broke it, with an explanation of why it broke. git bisect does the search; your job is building a reliable oracle and driving the machine.
Phase 1 — Build the oracle
Translate the symptom into an executable check script that exits 0 when the behavior is good and non-zero when it's bad. This script is everything — a wrong oracle bisects to a wrong commit with total confidence.
- Prefer the narrowest observable signal: a failing test, a grep on output, an HTTP probe, an exit code — not "run the app and look."
- Validate the oracle before trusting it: it must fail at the suspected-bad ref (usually HEAD) and pass at some older ref. If the user can't name a good ref, probe backwards — last release tag, then earlier tags/dates — until the check passes. No verified good/bad pair, no bisect.
- If the symptom is flaky, make the oracle run the check N times and fail on any failure (or majority, if the flake is inverse). State the confidence tradeoff.
Phase 2 — Drive the machine
- Work in a separate worktree (
git worktree add) so the user's working directory is untouched. git bisect start <bad> <good>, thengit bisect run <oracle>.- Handle history friction:
- Commit doesn't build for unrelated reasons →
git bisect skip. - Build/setup steps changed across history → make the oracle detect and adapt (e.g. try both old and new install commands), or bisect in stages across the boundary.
- Dependencies must match each era — reinstall per checkout if lockfiles change.
- Commit doesn't build for unrelated reasons →
- If
bisect runcan't work (manual-only check), fall back to stepping manually and asking the user to observe only when unavoidable — automate everything else.
Phase 3 — The verdict
Never stop at the commit hash. Deliver:
- The guilty commit — hash, author, date, message.
- The mechanism — read the diff and explain how this change produces the observed symptom. If the connection isn't obvious, trace it until it is; a bisect result you can't explain is a suspect, not a conviction.
- The options — clean revert (test whether it reverts cleanly and whether the symptom disappears), or a forward fix sketch, with a recommendation.
Cleanup
Always git bisect reset and remove the worktree, even after failure. Leave no machinery behind.
Edge cases
- Merge-heavy history: if the guilty commit is a merge, bisect the merged branch's commits (
git bisecthandles this, but explain the result carefully). - The oracle passes everywhere / fails everywhere: the good/bad pair was wrong or the symptom is environmental (data, config, dependency drift — not the repo's history). Say so; that's a real answer.
- Very expensive checks: estimate steps first (
log --oneline good..bad | wc -l→ log₂) and tell the user the cost before starting.