Menu
Binary search for root cause: define a search space and a pass/fail oracle, then halve the space each step until the culprit commit, config key, or dependency is isolated. Works across git history, configuration, dependencies, or code modules.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | bisect |
| description | Binary search for root cause: define a search space and a pass/fail oracle, then halve the space each step until the culprit commit, config key, or dependency is isolated. Works across git history, configuration, dependencies, or code modules. |
| scope | universal |
| ported-from | bisect command |
Define a search space and a pass/fail oracle, then iteratively test midpoints, halving the space each step until the root cause is isolated. Works across git history, configuration, dependencies, or code modules.
"description of the bug or regression"
Work with the user to establish four things before starting the search loop.
1. The symptom: what is broken? What does failure look like? Get a concrete, observable description (error message, wrong output, crash, performance degradation).
2. The search dimension: where to search. Determine which applies:
3. The test oracle: how to determine pass/fail at each midpoint:
npm test, pytest tests/foo.py, go test ./..., etc.)4. Known bounds: the "good" end and "bad" end of the search space.
For git history bisect, run:
git log --oneline <good_commit>..<bad_commit>
to enumerate the search space. Count the candidates and report: "Search space: N commits. Expected steps: ceil(log2(N))."
For configuration bisect, list all changed config keys between the working and broken state. For dependency bisect, list all upgraded packages with old and new versions sorted by update date.
Present the search space summary to the user and confirm before proceeding. Adjust if the user gives feedback.
Execute the bisect algorithm. This is strictly sequential, each step depends on the previous result.
iteration = 0
while search_space > 1:
iteration += 1
midpoint = calculate_midpoint(search_space)
# Spawn a test agent at the midpoint
agent = spawn_test_agent(midpoint, test_oracle)
result = agent.run() # PASS or FAIL
if result == FAIL:
# Bug exists at midpoint: narrow to the first half
bad_bound = midpoint
else:
# Bug absent at midpoint: narrow to the second half
good_bound = midpoint
report_progress(iteration, midpoint, result, remaining_space)
At each midpoint commit, spawn an agent with subagent_type: "general-purpose" that:
isolation: "worktree" to run in an isolated copy of the repo checked out at the midpoint commitgit worktree remove /tmp/bisect-<short_sha>)Sort the changed config keys into a list. At each step:
Sort dependencies by update date. At each step:
After each iteration, report to the user:
Step N: Testing [midpoint identifier]
Result: PASS / FAIL
Remaining search space: M candidates
Narrowed to: [new bounds description]
If a midpoint produces an inconclusive result (flaky test, build failure unrelated to the bug, untestable state), stop and ask the user:
Once the search space narrows to a single item (one commit, one config key, one dependency):
git show <culprit_commit> and walk through the relevant hunksPresent the final report:
Root Cause The specific change that introduced the regression, with a one-line summary.
Bisect Log A table of every step: iteration number, midpoint tested, result (PASS/FAIL), remaining search space after that step.
Analysis Why the identified change caused the regression. Include relevant code snippets or config values.
Fix Options Ranked remediation paths:
Search Efficiency How many steps were taken versus the theoretical minimum of ceil(log2(N)). Note any skipped midpoints.
git worktree prune at the end of a git bisect.Standalone debugging tool. Does not chain with the ideation-to-implementation pipeline:
bug report / regression → /bisect → root cause + fix proposal
Index of this project's coding-practice rules — architecture, coding style, testing, security, git workflow, task management, context layering, anti-slop, performance, and language-specific rules. The thin always-on essentials live in .claude/rules/common/house-rules.md; the full per-topic detail ships under .claude/rules/reference/ and .claude/rules/<lang>/ and is read on demand. Invoke this skill when you need the project's standards for a task, then open the specific rule file it points to.
Thin methodology for end-to-end tests of critical user journeys — define journeys by risk, use semantic locators and condition-based waits, quarantine flaky tests with a tracked reason, and capture artifacts on failure. Use when adding or stabilizing E2E coverage; the e2e-runner agent applies it in depth.
Design rigorous evaluations and benchmarks for AI agents, developer tools, retrieval systems, and repository-scale automation. Covers task selection, contamination control, metric choice tied to engineering decisions, and statistical validity. Use when asked to design an eval/benchmark, critique an existing benchmark, choose metrics for an agent or RAG system, or decide whether a measured improvement is real. NOT for running an existing performance-benchmark suite or a per-feature acceptance checklist, or one-off model spot-checks.
Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree one at a time. Use for ambiguous or complex collaborative specs before any code is written.
Decision framework for choosing between regex and LLM when parsing structured text — start with regex, add LLM only for low-confidence edge cases. Use when parsing quizzes, forms, invoices, or documents with repeating structure and cost matters.
Review a repository for long-term architectural leverage rather than code quality — system structure, module boundaries, dependency graph, coupling, and drift. Produces a ranked set of highest-ROI improvements with evidence, effort, and risk. Use when asked to review the architecture, assess a codebase's structure/design, find where complexity is concentrated, or decide what to refactor next. NOT for style, naming, formatting, or line-level bugs (use a code-review skill for those).