bisect.md
markdown
| 1 | # `muse bisect` — binary search for regressions |
| 2 | |
| 3 | `muse bisect` is a **regression-hunting power tool** for humans and agents alike. Given a commit where a bug first appears (bad) and a commit where it was not present (good), it performs a binary search through the history between them — cutting the search space in half at each step — until the exact commit that introduced the bug is isolated. |
| 4 | |
| 5 | For a 1,000-commit range, `muse bisect` needs at most 10 steps. For 1,000,000, it needs 20. |
| 6 | |
| 7 | ## Subcommands |
| 8 | |
| 9 | | Command | Description | |
| 10 | |---------|-------------| |
| 11 | | `muse bisect start` | Begin a bisect session | |
| 12 | | `muse bisect bad [ref]` | Mark a commit as bad (bug present) | |
| 13 | | `muse bisect good [ref]` | Mark a commit as good (bug absent) | |
| 14 | | `muse bisect skip [ref]` | Skip a commit that cannot be tested | |
| 15 | | `muse bisect run <cmd>` | Automatically bisect using a shell command | |
| 16 | | `muse bisect log` | Show the bisect session log | |
| 17 | | `muse bisect reset` | End the session and clean up state | |
| 18 | |
| 19 | ## Manual workflow |
| 20 | |
| 21 | ```bash |
| 22 | # 1. Start the session with the bad and good bounds: |
| 23 | muse bisect start --bad HEAD --good v1.0.0 |
| 24 | |
| 25 | # 2. Muse suggests a midpoint: |
| 26 | # Next to test: a1b2c3d4ef56 (32 remaining, ~5 steps left) |
| 27 | |
| 28 | # 3. Test that commit and report the result: |
| 29 | muse bisect good # or: muse bisect bad |
| 30 | |
| 31 | # 4. Repeat until the first bad commit is found: |
| 32 | # ✅ First bad commit found: deadbeef1234… |
| 33 | # Run 'muse bisect reset' to end the session. |
| 34 | |
| 35 | # 5. Clean up: |
| 36 | muse bisect reset |
| 37 | ``` |
| 38 | |
| 39 | ## Automated workflow (`muse bisect run`) |
| 40 | |
| 41 | The `run` subcommand fully automates the search. The command you provide is run at each bisect step; the exit code determines the verdict: |
| 42 | |
| 43 | | Exit code | Verdict | |
| 44 | |-----------|---------| |
| 45 | | `0` | good — bug not present | |
| 46 | | `125` | skip — commit untestable (e.g. build fails) | |
| 47 | | `1–124`, `126–255` | bad — bug present | |
| 48 | |
| 49 | ```bash |
| 50 | muse bisect start --bad HEAD --good v1.0.0 |
| 51 | muse bisect run "pytest tests/test_regression.py -x -q" |
| 52 | ``` |
| 53 | |
| 54 | Muse will automatically advance until the first bad commit is found. |
| 55 | |
| 56 | ## State file |
| 57 | |
| 58 | The bisect session is stored at `.muse/BISECT_STATE.toml`: |
| 59 | |
| 60 | ```toml |
| 61 | bad_id = "deadbeef…" |
| 62 | good_ids = ["aabbccdd…"] |
| 63 | skipped_ids = [] |
| 64 | remaining = ["a1b2c3…", "d4e5f6…", …] |
| 65 | log = ["deadbeef… bad 2026-03-19T14:22:01+00:00", …] |
| 66 | branch = "main" |
| 67 | ``` |
| 68 | |
| 69 | The state file is rebuilt at every step so it survives interruptions. |
| 70 | |
| 71 | ## Multiple good commits |
| 72 | |
| 73 | You can specify multiple `--good` bounds to narrow the search range from multiple known-good ancestors: |
| 74 | |
| 75 | ```bash |
| 76 | muse bisect start --bad HEAD --good v1.0.0 --good v1.1.0 --good v1.2.0 |
| 77 | ``` |
| 78 | |
| 79 | ## Agent workflow |
| 80 | |
| 81 | ```bash |
| 82 | # Fully autonomous regression hunt: |
| 83 | muse bisect start --bad HEAD --good "$LAST_GREEN_CI_COMMIT" |
| 84 | muse bisect run "./ci/test.sh" |
| 85 | # Agent reads the result and files a bug report with the first-bad commit. |
| 86 | ``` |
| 87 | |
| 88 | ## Exit codes |
| 89 | |
| 90 | | Code | Meaning | |
| 91 | |------|---------| |
| 92 | | 0 | Success | |
| 93 | | 1 | No bisect session active, or ref not found | |
| 94 | |
| 95 | ## Interaction with other commands |
| 96 | |
| 97 | - `muse bisect` operates on **existing commits** in the store — it does not check out files automatically. For file-level testing, use `muse bisect run` with a script that reads `state/` directly. |
| 98 | - After `muse bisect reset`, all bisect state is removed and the normal branch workflow resumes. |