Skip to content
Skills Library
Programming · Analysis

git-bisect-assistant

/git-bisect-assistant

Automatically performs git bisect to identify the first bad commit that introduced a bug or failure. Use when debugging regressions, tracking down when a test started failing, or identifying which commit broke functionality. Handles flaky tests with retry logic and provides comprehensive reports with bisect logs and confidence levels.

Repository
Skills-4-SE ↗
Licence
Apache-2.0
Last repository change
21.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 21.08.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/git_bisect_runner.py

What it does and when to use it

Automatically performs git bisect to identify the first bad commit that introduced a bug or failure. Use when debugging regressions, tracking down when a test started failing, or identifying which commit broke functionality. Handles flaky tests with retry logic and provides comprehensive reports with bisect logs and confidence levels.

Original author description

Automatically performs git bisect to identify the first bad commit that introduced a bug or failure. Use when debugging regressions, tracking down when a test started failing, or identifying which commit broke functionality. Handles flaky tests with retry logic and provides comprehensive reports with bisect logs and confidence levels.

How it works

  1. Quick Start
  2. Workflow
  3. Parameters
  4. Handling Flaky Tests
  5. Test Command Guidelines
  6. Output Report
  7. Common Scenarios
  8. Tips
  9. Troubleshooting
Original SKILL.md headings · 159 lines, 639 words
SKILL.md preview
---
name: git-bisect-assistant
description: Automatically performs git bisect to identify the first bad commit that introduced a bug or failure. Use when debugging regressions, tracking down when a test started failing, or identifying which commit broke functionality. Handles flaky tests with retry logic and provides comprehensive reports with bisect logs and confidence levels.
---

# Git Bisect Assistant

Automates the git bisect process to efficiently identify the first bad commit responsible for a bug or test failure.

## Quick Start

Basic usage pattern:

```bash
python scripts/git_bisect_runner.py \
  --good <known-good-commit> \
  --bad <known-bad-commit> \
  --test "<test-command>"
```

Example:

```bash
python scripts/git_bisect_runner.py \
  --good v1.0.0 \
  --bad HEAD \
  --test "pytest tests/test_feature.py::test_specific_case"
```

## Workflow

1. **Gather Information**
   - Identify the known good revision (commit, tag, or branch)
   - Identify the known bad revision (defaults to HEAD)
   - Determine the test command that fails on bad commits and passes on good commits

2. **Run Bisect**
   - Execute the `git_bisect_runner.py` script with appropriate parameters
   - The script will automatically test commits and narrow down the culprit

3. **Review Results**
   - Examine the identified bad commit
   - Review the bisect log showing all tested commits
   - Check confidence level and assumptions

## Parameters

### Required

- `--good`: Known good revision (commit hash, tag, or branch name)
- `--test`: Shell command to test each commit. Exit code 0 = good, non-zero = bad

### Optional

- `--bad`: Known bad revision (default: `HEAD`)
- `--repo`: Repository path (default: current directory)
- `--retries`: Number of test runs per commit for flaky tests (default: 1)
- `--timeout`: Test execution timeout in seconds (default: no timeout)

## Handling Flaky Tests

For non-deterministic tests, use `--retries` to run the test multiple times per commit:

```bash
python scripts/git_bisect_runner.py \
  --good abc123 \
  --bad HEAD \
  --test "npm test" \
  --retries 3
```

The script uses majority voting: if a test passes 2 out of 3 times, the commit is marked as good.

## Test Command Guidelines

The test command should:
- Exit with code 0 for good commits (test passes)
- Exit with non-zero code for bad commits (test fails)
- Be deterministic or use `--retries` for flaky tests
- Complete within reasonable time or use `--timeout`

Examples:

```bash
# Python test
--test "pytest tests/test_auth.py -v"

# Shell script
--test "./scripts/verify_build.sh"

# Compilation check
--test "make && ./bin/app --version"

# Multiple commands
--test "npm install && npm test"
```

## Output Report

The script generates a comprehensive report including:

- **First Bad Commit**: Hash and commit message of the culprit
- **Confidence Level**: Assessment based on test stability and retry logic
- **Assumptions**: Any assumptions made during bisect (retries, timeouts)
- **Tested Commits**: Complete list of all commits tested with results
- **Bisect Log**: Detailed log of the bisect process

## Common Scenarios

### Scenario 1: Test Started Failing

User: "The integration tests started failing sometime in the last 20 commits"

```bash
python scripts/git_bisect_runner.py \
  --good HEAD~20 \
  --bad HEAD \
  --test "pytest tests/integration/"
```

### Scenario 2: Feature Broke After Release

User: "Feature X worked in v2.1.0 but is broken now"

```bash
python scripts/git_bisect_runner.py \
  --good v2.1.0 \
  --bad HEAD \
  --test "python -c 'import app; assert app.feature_x() == expected'"
```

### Scenario 3: Flaky Test Investigation

User: "A test fails intermittently, need to find when it started"

```bash
python scripts/git_bisect_runner.py \
  --good main \
  --bad feature-branch \
  --test "pytest tests/test_flaky.py" \
  --retries 5 \
  --timeout 30
```

## Tips

- **Ensure clean state**: Commit or stash changes before running bisect
- **Fast tests**: Use focused tests rather than full test suites for faster bisect
- **Build requirements**: Include build steps in test command if needed
- **Dependencies**: Ensure test command handles dependency installation if needed across commits
- **Timeout wisely**: Set timeout slightly longer than expected test duration
- **Retry count**: Use 3-5 retries for flaky tests to get reliable results

## Troubleshooting

**Bisect fails to start**: Verify good and bad revisions exist and are valid git references

**Test command fails unexpectedly**: Test the command manually on a known good/bad commit first

**Inconsistent results**: Increase `--retries` or check for environmental factors affecting tests

**Timeout too short**: Increase `--timeout` or optimize test command
Files in this package (2)
  • SKILL.md 5 KB
  • scripts/git_bisect_runner.py 8 KB

Versions

The database has no other skills named git-bisect-assistant.

Database snapshot: 13.11.2026 · package version 5e7958d9966e (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100git-bisect-regression
    Find which commit introduced a bug or behavior change using `git bisect`. Use this whenever the user says something "used to work", "worked last week", "stopped working", "broke at some point", asks "which commit broke this", "when did this start", "find the regression" or "who…
  • 90git-bisect
    Find the exact commit that introduced a regression by driving git bisect with an automated pass/fail script. Use when a behavior worked in an older build and you need the first bad commit out of hundreds, not a guess.
  • 100bisect-anything
    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…
  • 100bisect-aware-instrumentation
    Instrument code to support efficient git bisect by producing deterministic pass/fail signals and concise runtime summaries for each tested commit. Use when debugging regressions with git bisect, automating bisect workflows, creating bisect test scripts, handling flaky tests…
  • 100git-bisect-debugging
    This skill should be used when the user asks to "find which commit broke this", "debug a regression", "bisect to find the bug", or says "this used to work". Automatically activates for performance regressions, test failures that appeared recently, or any issue known to have…
  • 100git-bisect-hunting-regression-bugs
    Use this skill when pinpointing the exact commit introducing a software defect using automated binary search with git bisect.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.