sjungling/git-bisect-debugging

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.

Critical Rules

These are non-negotiable. No exceptions for time pressure, production incidents, or "simple" cases:

1. ANNOUNCE skill usage at start
2. CREATE TodoWrite checklist immediately (copy from "The Process" below)
3. VERIFY safety checks in Phase 1 -- working directory must be clean, good commit must be verified good, bad commit must be verified bad. If any check fails, abort and fix before proceeding.
4. USE AskUserQuestion for strategy selection in Phase 2 -- present all 3 approaches, do not default to automated without asking
5. LAUNCH subagents for verification in Phase 3 -- never run verification in main context; each commit tested in isolated subagent via Task tool
6. HANDOFF to systematic-debugging in Phase 4 -- after finding the bad commit, investigate root cause, not just what changed

If tempted to skip any rule: STOP. Follow the 4-phase workflow exactly. Skipping safety checks, skipping TodoWrite, defaulting to automated, running tests in main context, or stopping after finding the commit are all violations.

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