Skip to content
Skills Library
Programming · Analysis

git-bisect-debugging

/git-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 worked at a previous commit. Can be invoked from systematic-debugging or used standalone. Not for general debugging without a known-good commit or regression history.

Licence
MIT
Last repository change
22.10.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
4
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

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

Licence

MIT, open: use and modify while retaining author attribution.

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

Scripts: scripts/bisect-test-template.sh

What it does and when to use it

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 worked at a previous commit. Can be invoked from systematic-debugging or used standalone. Not for general debugging without a known-good commit or regression history.

Triggers from the description

find which commit broke thisdebug a regressionbisect to find the bugthis used to work
Original author description

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 worked at a previous commit. Can be invoked from systematic-debugging or used standalone. Not for general debugging without a known-good commit or regression history.

How it works

  1. Overview
  2. Quick Reference
  3. Limitations (By Design)
  4. Rules
  5. The Process
  6. Additional Resources
Original SKILL.md headings · 156 lines, 950 words
SKILL.md preview
---
name: git-bisect-debugging
description: 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 worked at a previous commit. Can be invoked from systematic-debugging or used standalone. Not for general debugging without a known-good commit or regression history.
---

# Git Bisect Debugging

## Overview

Systematically identify which commit introduced a bug or regression using git bisect. Binary search through commit history to find the exact commit that introduced the issue. Main agent orchestrates, subagents execute verification at each step.

**Announce at start:** "I'm using git-bisect-debugging to find which commit introduced this issue."

## Quick Reference

| Phase | Key Activities | Output |
|-------|---------------|--------|
| **1. Setup & Verification** | Identify good/bad commits, verify clean state | Confirmed commit range |
| **2. Strategy Selection** | Choose automated/manual/hybrid approach | Test script or verification steps |
| **3. Execution** | Run bisect with subagents | First bad commit hash |
| **4. Analysis & Handoff** | Show commit details, analyze root cause | Root cause understanding |

## Limitations (By Design)

This skill focuses on straightforward scenarios. It does NOT handle:

- Complex merge commit issues (would need `--first-parent`)
- Flaky/intermittent test failures (would need statistical approaches)
- Build system failures across many commits (would need advanced skip strategies)

For these scenarios, manual git bisect with user guidance is recommended.

## Rules

Announce the skill and track the four phases in a checklist. Then:

1. Phase 1: confirm the working directory is clean and the good commit is verified good and the bad commit verified bad. A bisect over a wrong range wastes the whole run; if a check fails, fix it before proceeding.
2. Phase 2: ask the user which strategy to use (automated, manual, hybrid) rather than defaulting to automated.
3. Phase 3: test each commit in an isolated subagent so the main context stays clean.
4. Phase 4: after finding the bad commit, hand off to systematic-debugging to investigate root cause, not just what changed.

## The Process

Copy this checklist to track progress:

```
Git Bisect Progress:
- [ ] Phase 1: Setup & Verification (good/bad commits identified)
- [ ] Phase 2: Strategy Selection (approach chosen, script ready)
- [ ] Phase 3: Execution (first bad commit found)
- [ ] Phase 4: Analysis & Handoff (root cause investigation complete)
```

### Phase 1: Setup & Verification

**Purpose:** Ensure git bisect is appropriate and safe to run.

**Steps:**

1. **Verify prerequisites:**
   - Verify the current directory is a git repository
   - Verify working directory is clean (`git status`)
   - If uncommitted changes exist, abort and ask user to commit or stash

2. **Identify commit range:**
   - Ask user for **good commit** (where it worked)
     - Suggestions: last release tag, last passing CI, commit from when it worked
     - Commands to help: `git log --oneline`, `git tag`, `git log --since="last week"`
   - Ask user for **bad commit** (where it is broken)
     - Usually: `HEAD` or a specific commit where issue is confirmed
   - Calculate estimated steps: ~log2(commits between good and bad)

3. **Verify the range:**
   - Checkout bad commit and verify issue exists
   - Checkout good commit and verify issue does not exist
   - If reversed, offer to swap them
   - Return to original branch/commit

4. **Safety checks:**
   - Warn if range is >1000 commits (ask for confirmation)
   - Verify good commit is ancestor of bad commit
   - Note current branch/commit for cleanup later

**Output:** Confirmed good commit hash, bad commit hash, estimated steps

### Phase 2: Strategy Selection

**Purpose:** Choose the most efficient bisect approach.

**Assessment:** Determine whether an automated test script can deterministically identify good vs bad.

**MANDATORY: Use AskUserQuestion** to present three approaches:
1. **Automated** -- test script runs automatically (best for: test failures, crashes, deterministic behavior)
2. **Manual** -- user verifies each commit (best for: UI/UX changes, subjective issues)
3. **Hybrid** -- script + manual confirmation (best for: mostly automated with judgment calls)

**If automated or hybrid selected:**

Write a test script following the template at `./scripts/bisect-test-template.sh`. Key guidelines:
- Make it deterministic (no random data, use fixed seeds)
- Make it fast (runs ~log2(N) times)
- Exit codes: 0 = good, 1 = bad, 125 = skip
- Include build/setup (each commit might need different deps)
- Test ONE specific thing, not the entire suite

**If manual selected:**

Write specific verification steps for the subagent with concrete actions and expected outcomes. Avoid vague instructions like "see if it works."

**Output:** Selected approach, test script or verification steps

### Phase 3: Execution

**Architecture:** Main agent orchestrates bisect, subagents verify each commit in isolated context.

For detailed subagent prompt templates and error handling patterns, see `./references/execution-patterns.md`.

**Execution summary:**

1. Run `git bisect start <bad> <good>`
2. Loop: launch subagent via Task tool to verify current commit -> report good/bad/skip -> run `git bisect good|bad|skip` -> update progress
3. Run `git bisect reset` to cleanup
4. Return to original branch/commit

**Output:** First bad commit hash, bisect log showing the path taken

### Phase 4: Analysis & Handoff

**Purpose:** Present findings and analyze root cause.

1. **Present the identified commit:**
   ```
   Found first bad commit: <hash>
   Author: <author>
   Date: <date>
   <commit message>
   Files changed: <list from git show --stat>
   ```

2. **Show how to view details:**
   ```
   View full diff: git show <hash>
   View file at that commit: git show <hash>:<file>
   ```

3. **Handoff to root cause analysis:**
   - Announce: "Now that the breaking commit is identified at `<hash>`, using systematic-debugging to analyze why this change caused the issue."
   - Use superpowers:systematic-debugging skill to investigate
   - Focus analysis on the changes in the bad commit
   - Identify the specific line/change that caused the issue
   - Explain WHY it broke (not just WHAT changed)

**Output:** Root cause understanding of why the commit broke functionality

## Additional Resources

- **`./references/execution-patterns.md`** -- Subagent prompt templates and error handling
- **`./references/troubleshooting.md`** -- Common patterns, troubleshooting, and example workflows
- **`./scripts/bisect-test-template.sh`** -- Test script template for automated bisect
Files in this package (4)
  • SKILL.md 7 KB
  • references/execution-patterns.md 3 KB
  • references/troubleshooting.md 3 KB
  • scripts/bisect-test-template.sh 1 KB

Versions

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

Database snapshot: 13.11.2026 · package version 61208f84778c (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…
  • 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…
  • 100git-bisect-hunting-regression-bugs
    Use this skill when pinpointing the exact commit introducing a software defect using automated binary search with git bisect.
  • 100git-bisect-ai
    AI-guided git bisect for finding the exact commit that introduced a bug or regression. Automates the binary search, interprets test results, and identifies the responsible code change with full context. Use when you know a bug exists now but didn't exist before, or when a…
  • 100git-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…
  • 100bisect
    Bisect a ClickHouse regression using pre-built master binaries from CI. Use when the user wants to find the commit that introduced a bug.

Feedback and reports

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