Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add dotslashsimran/simcraft --skill bisect-anything -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/bisect-anything/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/bisect-anything/

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

Similar skills

All skills for Git and GitHub →

From the same set24

The whole set →
from-scratch The from-scratch Claude Code skill teaches how a technology works by building a small version step by step. Before each run, the agent asks for a prediction, then checks it against the program’s output. CX Codex +1 ★ 541repo stars video-script The video-script Claude Code skill drafts short talking-head, explainer, and product-demo videos. It activates for requests to write or revise a script, hook, or YouTube, TikTok, Reels, or LinkedIn video. CX Codex +1 ★ 541repo stars repo-timelapse The repo-timelapse Claude Code skill turns a repository’s Git history into a video of the project changing over time. It runs on requests to show project growth or animate commits. CX Codex +1 ★ 541repo stars skill-router The skill-router Claude Code skill selects a matching skill or builds a sequence for a task. It kicks in when a request is vague or could call for several skills. CX Codex +1 ★ 541repo stars scripted-screencast The scripted-screencast Claude Code skill turns scripted browser actions into a product demo video with cursor effects, zooms, and captions. It activates for screencast requests and rerenders after interface changes. CX Codex +1 ★ 541repo stars security-threat-model The security-threat-model Claude Code skill maps threats from an app’s code and tests the highest risks locally. It activates for requests about STRIDE, app security reviews, or vulnerabilities before launch. CX Codex +1 ★ 541repo stars vox-explainer The vox-explainer Claude Code skill makes Vox-style explainer graphics or a faceless video. It runs on requests for voiceover-led visuals, animated quotes, or stats. CX Codex +1 ★ 541repo stars benchmark-honestly The benchmark-honestly Claude Code skill checks performance measurements and compares code versions. It activates for benchmark requests, load tests, latency percentiles, or claims that a change made code faster. CX Codex +1 ★ 541repo stars

Project sponsors

Companies that keep this analytics open