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.
- Author
- sjungling ↗
- Repository
- sjungling-claude-plugins ↗
- Licence
- MIT
- Last repository change
- 22.10.2026
Assessment and security
- Files in this package
- 4
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 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
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
- Overview
- Quick Reference
- Limitations (By Design)
- Rules
- The Process
- Additional Resources
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.