Bisect the Change
Finds what broke it by halving the search space instead of touring the suspects.
When to reach for it
When something worked before and does not now, and nobody can point at why — after a merge, a dependency bump, or a week of commits nobody looked at closely.
What changes
- The agent establishes a known-good point and a known-bad point first, so the search is bounded instead of open-ended.
- One repeatable check decides good or bad at every step, applied identically each time.
- The range halves each round, so a hundred commits resolve in about seven runs rather than a tour of the ones that look suspicious.
- The result is a single change identified by evidence, confirmed by reverting it in isolation and watching the symptom go.
- When the cause is not in your code, the same halving gets applied to dependencies, config or data instead of stopping at 'must be the library'.
Pairs with
- It Worked YesterdayFinds what changed when, as far as you know, nothing changed.
- Read the Actual ErrorReads what the error really says — the file, the values, the chain — before matching it to a bug you have seen before.
- Reproduce Before FixRequires a failing case you can run on demand before a single line gets changed.
Bisect the Change
Something worked and now does not. Find the change by halving, not by intuition.
1. Write the check that decides
One command or one short sequence with an unambiguous outcome. It has to be fast enough to run twenty times and stable enough that the same code always gives the same answer. If it is flaky, fix that first — a flaky check bisects to a random change with total confidence.
2. Find a known-good point
Go back until the check passes. If the oldest point you can reach still fails, either the bug is older than you assumed or your check is wrong. Test the second possibility before believing the first.
You now have a bounded range: this one passes, that one fails.
3. Halve it
Take the midpoint. Run the check. Whichever half still contains the transition becomes the new range. Repeat. A hundred commits takes about seven runs.
Use your version control's built-in bisect if it has one, and mark each step honestly. If a midpoint will not build, mark it skipped rather than guessing which way it would have gone.
4. Confirm the culprit
The change the search names is a hypothesis until you test it: revert it on its own and confirm the check passes, then reapply it and confirm the check fails.
5. When it is not in your commits
Same method, different axis. Halve the version bumps in the lockfile. Halve the config differences between the working machine and the broken one. Halve the data — the failing input probably still fails with half its rows removed. The technique is not about commits, it is about cutting the space in two.
6. Then understand it before fixing
You know what changed. Work out why it broke before reverting, because the change was often correct and merely exposed something else.
Rules
- Do not skip the known-good point. Without it the range is unbounded and you cannot tell when to stop.
- Do not modify the check between steps. A moving check invalidates every comparison you have already made.
- Do not stop at the first suspicious-looking change. Suspicion is exactly what this method exists to replace.
- Do not revert and move on without an explanation. An unexplained revert is a bug that returns the next time someone tries that change.