bisect-anything — Claude Code skill for finding regressions
The bisect-anything Claude Code skill tracks a regression to a commit, dependency version, or config value. It activates for requests to find what broke a test or when a problem began.
MIT ★ 541 updated 2026-11-09
npx skills add dotslashsimran/simcraft --skill bisect-anything -a claude-codeWhat bisect-anything does
The skill turns a regression symptom into a pass/fail check, then runs git bisect run in a separate worktree. The check must confirm both the known-good and known-bad revisions first. A failed build or install marks that revision as skipped.
It provides different check patterns for failing tests, changed output, slowdowns, crashes, screenshots, and server behaviour. Its scripts require Python 3.9+ and use only the standard library. Another script can reduce the culprit commit to the specific hunks that trigger the issue. The separate worktree leaves the current checkout and uncommitted changes untouched.
What it helps with
- find the commit that made a test fail
- trace a slowdown to a dependency version
- compare output or screenshots across a regression
- reduce a culprit commit to the relevant hunks
Example prompts for the agent
- Find the commit that made this test start failing.
- Track the slowdown to the dependency version that caused it.
- Identify the commit change that altered this screenshot.
How to install bisect-anything
1Skills CLI (Vercel)
npx skills add dotslashsimran/simcraft --skill bisect-anything -a claude-code2Manually: put the files in place
~/.claude/skills/bisect-anything/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/bisect-anything/
1Skills CLI (Vercel)
npx skills add dotslashsimran/simcraft --skill bisect-anything -a codex2Manually: put the files in place
.agents/skills/bisect-anything/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add dotslashsimran/simcraft --skill bisect-anything -a cursor2Manually: put the files in place
.cursor/skills/bisect-anything/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install dotslashsimran/simcraft skills/coding/bisect-anything2Manually: put the files in place
.github/skills/bisect-anything/SKILL.md1Skills CLI (Vercel)
npx skills add dotslashsimran/simcraft --skill bisect-anything -a gemini-cli2Platform CLI
gemini skills install https://github.com/dotslashsimran/simcraft --path skills/coding/bisect-anythingManually: put the files in place
.devin/skills/bisect-anything/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about bisect-anything
How do I install bisect-anything in Claude Code?
Run npx skills add dotslashsimran/simcraft --skill bisect-anything -a claude-code. The skill file is installed at ~/.claude/skills/bisect-anything/SKILL.md.
What does bisect-anything do?
It searches project history for the commit that introduced a regression, then narrows that commit to the changes associated with the problem.
What does bisect-anything need to run?
Its scripts require Python 3.9+ and use only the standard library. The check also runs git bisect run in a separate worktree.
Source text
SKILL.md · MIT
--- name: bisect-anything description: 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 tests, changed output, slowdowns, crashes, visual changes, server behaviour, flaky checks, unbuildable commits and merge-heavy history. Use when the user says "what broke this", "find the commit that", "when did this start", "it used to work", "regression", "git bisect", "which version broke it", or "which change made it slow". --- # Bisect anything A bisect is only as good as its oracle: the command that says "good" or "bad" for one commit. Almost every wrong bisect answer comes from an oracle that is flaky, tests the wrong thing, or calls a broken build "bad". So spend most of the effort on the oracle, prove it on both ends, and let the scripts do the rest. Scripts are in `~/simcraft/skills/coding/bisect-anything/scripts/` (Python 3.9+, standard library only). Details, recipes and pitfalls are in `reference.md` next to this file. ## 1. Pin down the regression Ask only for what is missing, one question at a time: - **What is wrong**, as something a command can check (a failing test, a wrong number, a slow page, a crash, a changed screenshot). - **A good point**: a tag, release, date or commit where it worked. If nobody knows, try an old tag; checking one old commit is cheap. - **The bad point**: usually `HEAD`. - **How to build and install** at an old commit. ## 2. Write the oracle Exit `0` good, `125` cannot test this commit, any other code bad. Keep the oracle script **outside the repo** (or pass it with `--overlay`), because old commits do not have it. Pick the recipe that fits; full versions are in `reference.md`: | Regression | Oracle | |---|---| | A test fails | run that one test only, with `--overlay` if the test is new | | Output changed | `oracles/golden_oracle.py`, with `--ignore` for times, versions and ids | | Got slower | `oracles/bench_oracle.py`: measure both ends first, threshold between the medians | | Crash | exit 1 only for the crash signature (signal or message), 0 otherwise | | Looks different | render a screenshot, then `oracles/img_diff.py` with a tolerance and masks | | Server behaviour | `oracles/serve_oracle.py`: free port, wait until ready, probe, always kill | Narrow the oracle to this one bug. "The whole test suite passes" finds the first commit that broke anything, which is rarely the one the user cares about. ## 3. Run it ``` python3 scripts/bisect.py --good v2.3.0 --bad HEAD \ --install "npm ci" --build "npm run build" \ --oracle "node /path/outside/repo/repro.js" --repeats 3 --timeout 120 ``` It works in a separate worktree, so the user's checkout and uncommitted work are untouched. It first checks the oracle says good on `--good` and bad on `--bad`, and stops if not. Install runs only when a lockfile or manifest changes; a failed install or build marks the commit as skip (125). Choose flags with judgement: - Flaky oracle: `--repeats 5` (majority vote). A bug that only shows sometimes: `--repeats 10 --vote any-bad`. - Hangs: `--timeout`; a timeout counts as bad unless `--timeout-means skip`. - Merge-heavy history, or "which PR broke it": `--first-parent`, then bisect inside the merge it names. - Stale build output fools you: `--clean --keep node_modules`. - Looking for the fix instead: `--find-fix`. For things that are not commits (package versions, nightly builds, config values, data rows), use `scripts/bisect_list.py` over an ordered list, or `--minimise` to find the smallest set of flags or inputs that still fails. ## 4. Explain the commit 1. Read the found commit with `git show`. If the report says "not conclusive", the answer is one of the listed commits next to a skipped one. Say so honestly, do not pick one. 2. Shrink it: `scripts/hunk_minimise.py --commit <sha> --oracle ... --build ...` finds the smallest set of hunks that still causes the problem. 3. Tell the user, in plain words: the commit (hash, title, author, date), the exact hunk, **why** that change causes the symptom, and how sure you are (steps, skips, repeats). Suggest a fix or a revert, and a regression test built from the oracle. ## Check your work Run `python3 examples/selftest.py`. It builds a 40-commit demo repo with a planted bug, slowdown, visual change and unbuildable commits, and checks that every scenario finds the right commit (about one minute).
© dotslashsimran · MIT · dotslashsimran/simcraft