Agent skill

Bisect Aware Instrumentation

by ArabelaTso in ArabelaTso/Skills-4-SE

Instrument code to support efficient git bisect by producing deterministic pass/fail signals and concise runtime summaries for each tested commit.

Apache-2.0Auto-check passedTesting & QA

Install Bisect Aware Instrumentation

skills CLI
$ npx skills add ArabelaTso/Skills-4-SE --skill bisect-aware-instrumentation -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install ArabelaTso/Skills-4-SE bisect-aware-instrumentation --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/ArabelaTso/Skills-4-SE.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/bisect-aware-instrumentation .claude/skills/bisect-aware-instrumentation && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
bisect-aware-instrumentation
GitHub stars
253
Token cost
~2k tokens
SKILL.md length
363 words
Files
5 (incl. scripts, references)
Skills in repo
170
Repo updated
First seen
Licence
Apache-2.0

At a glance

Instrument code to support efficient git bisect by producing deterministic pass/fail signals and concise runtime summaries for each tested commit.

  • Works in 5 steps: Understand the Regression → Create Bisect Test Script → Add Determinism Safeguards → …
  • Debugging regressions with git bisect
  • SKILL.md covers Overview, Core Workflow, Instrumentation Patterns and Advanced Techniques, plus 4 more sections
  • Runs Shell and Python scripts from its folder; calls git, npm and make

What it does

Bisect Aware Instrumentation is an agent skill from ArabelaTso/Skills-4-SE. 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 during bisection, or needing clear exit codes and logging for automated bisect runs. Helps identify the exact commit that introduced a bug through automated testing.

Its SKILL.md is about 2k tokens, which your agent loads only when the skill is triggered. The skill folder holds 6 other files, including scripts and reference files (for example `references/exit_codes.md`, `references/git_bisect_guide.md` and `scripts/bisect_template.sh`).

It sits in Testing & QA, covering Failing and flaky tests and Git workflow. It works with Git. The repository describes itself as: A curated list of 180+ useful Claude Skills for Software Engineering and resources for customizing AI for SE workflows. The licence is Apache-2.0.

When your agent uses it

  • Debugging regressions with git bisect
  • Automating bisect workflows
  • Creating bisect test scripts
  • Handling flaky tests during bisection

Example prompts

  • “/bisect-aware-instrumentation”

Requirements

  • Python 3
  • Node.js
  • A Bash shell

Workflow steps

5 steps, taken from the step headings in SKILL.md.

  1. Understand the Regression
  2. Create Bisect Test Script
  3. Add Determinism Safeguards
  4. Add Logging and Summaries
  5. Run Git Bisect

What it can do on your machine

Read from SKILL.md and the folder at commit 4f38503. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 2 files in scripts/ (Shell and Python), which the agent can run.

    Shell commands in SKILL.md call:

    • git
    • npm
    • make

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use git and npm, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Bisect Aware Instrumentation loads about 2k tokens when it runs, and up to ~6.3k if it reads all its reference files. Until then it costs about 117 tokens; SKILL.md has 363 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~117
When it runs · the whole SKILL.md, loaded when a task matches
~2k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~6.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from ArabelaTso/Skills-4-SE at commit 4f38503, republished under its Apache-2.0 licence (© ArabelaTso). 363 words, ~2,050 tokens.

Download SKILL.mdSave it as .claude/skills/bisect-aware-instrumentation/SKILL.md (or your agent's skills folder). This skill also uses 4 other files; get the full folder from GitHub.
name
bisect-aware-instrumentation
description
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 during bisection, or needing clear exit codes and logging for automated bisect runs. Helps identify the exact commit that introduced a bug through automated testing.

Bisect-Aware Instrumentation

Overview

Instrument code to support efficient git bisect operations by producing deterministic pass/fail signals and concise runtime summaries. This skill helps create robust test scripts that work reliably with git bisect run, handling edge cases like flaky tests, build failures, and non-deterministic behavior.

Core Workflow

1. Understand the Regression

Before instrumenting, clarify:

  • What behavior changed? (bug introduced, performance regression, test failure)
  • What is the "good" commit? (known working state)
  • What is the "bad" commit? (known broken state)
  • How to reproduce the issue? (test command, manual steps)
2. Create Bisect Test Script

Generate a test script that returns proper exit codes for git bisect:

Exit Code Convention:

  • 0: Good commit (test passes)
  • 1-124, 126-127: Bad commit (test fails)
  • 125: Skip commit (cannot test - build failure, missing dependencies)

Template:

bash
#!/bin/bash
# bisect_test.sh - Test script for git bisect run

set -e  # Exit on error

# Build/setup phase
if ! make build 2>/dev/null; then
    echo "SKIP: Build failed"
    exit 125
fi

# Run test with timeout
timeout 30s ./run_test || TEST_RESULT=$?

# Interpret results
if [ $TEST_RESULT -eq 0 ]; then
    echo "GOOD: Test passed"
    exit 0
elif [ $TEST_RESULT -eq 124 ]; then
    echo "SKIP: Test timeout"
    exit 125
else
    echo "BAD: Test failed with code $TEST_RESULT"
    exit 1
fi
3. Add Determinism Safeguards

Handle non-deterministic behavior:

Retry Logic for Flaky Tests:

bash
# Run test multiple times to confirm
PASS_COUNT=0
for i in {1..3}; do
    if ./run_test; then
        ((PASS_COUNT++))
    fi
done

if [ $PASS_COUNT -eq 3 ]; then
    echo "GOOD: All 3 runs passed"
    exit 0
elif [ $PASS_COUNT -eq 0 ]; then
    echo "BAD: All 3 runs failed"
    exit 1
else
    echo "SKIP: Flaky test ($PASS_COUNT/3 passed)"
    exit 125
fi

Environment Isolation:

bash
# Clean state before each test
rm -rf /tmp/test_cache
export RANDOM_SEED=42
export TZ=UTC
4. Add Logging and Summaries

Generate concise output for each commit:

bash
#!/bin/bash
COMMIT=$(git rev-parse --short HEAD)
LOG_FILE="bisect_log_${COMMIT}.txt"

echo "Testing commit: $COMMIT" | tee $LOG_FILE
echo "Timestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ)" | tee -a $LOG_FILE

# Run test and capture output
if ./run_test > test_output.txt 2>&1; then
    echo "RESULT: GOOD" | tee -a $LOG_FILE
    exit 0
else
    echo "RESULT: BAD" | tee -a $LOG_FILE
    echo "Error output:" | tee -a $LOG_FILE
    tail -20 test_output.txt | tee -a $LOG_FILE
    exit 1
fi
5. Run Git Bisect

Execute the bisect workflow:

bash
# Start bisect
git bisect start

# Mark known good and bad commits
git bisect bad HEAD
git bisect good v1.2.0

# Run automated bisect
chmod +x bisect_test.sh
git bisect run ./bisect_test.sh

# Review results
git bisect log

Instrumentation Patterns

Pattern 1: Performance Regression Detection
bash
#!/bin/bash
# Detect when performance drops below threshold

THRESHOLD=1000  # milliseconds

# Run benchmark
DURATION=$(./benchmark | grep "Duration:" | awk '{print $2}')

if [ -z "$DURATION" ]; then
    echo "SKIP: Benchmark failed to run"
    exit 125
fi

if [ $DURATION -lt $THRESHOLD ]; then
    echo "GOOD: Performance $DURATION ms (< $THRESHOLD ms)"
    exit 0
else
    echo "BAD: Performance $DURATION ms (>= $THRESHOLD ms)"
    exit 1
fi
Pattern 2: Test Suite Bisection
bash
#!/bin/bash
# Find commit that broke specific test

TEST_NAME="test_user_authentication"

# Run specific test
if pytest tests/${TEST_NAME}.py -v; then
    echo "GOOD: $TEST_NAME passed"
    exit 0
else
    echo "BAD: $TEST_NAME failed"
    exit 1
fi
Pattern 3: Build Failure Detection
bash
#!/bin/bash
# Find commit that broke the build

if make clean && make all; then
    echo "GOOD: Build succeeded"
    exit 0
else
    echo "BAD: Build failed"
    exit 1
fi
Pattern 4: Output Validation
bash
#!/bin/bash
# Find commit that changed program output

EXPECTED_OUTPUT="Success: 42"

ACTUAL_OUTPUT=$(./program 2>&1)

if [ "$ACTUAL_OUTPUT" = "$EXPECTED_OUTPUT" ]; then
    echo "GOOD: Output matches expected"
    exit 0
else
    echo "BAD: Output mismatch"
    echo "  Expected: $EXPECTED_OUTPUT"
    echo "  Actual: $ACTUAL_OUTPUT"
    exit 1
fi

Advanced Techniques

Handling Complex Build Systems
bash
#!/bin/bash
# Handle projects with complex dependencies

# Check if dependencies are available
if ! command -v node &> /dev/null; then
    echo "SKIP: Node.js not available in this commit"
    exit 125
fi

# Install dependencies (with caching)
if [ -f package.json ]; then
    npm ci --silent || {
        echo "SKIP: Dependency installation failed"
        exit 125
    }
fi

# Run test
npm test
Parallel Test Execution
bash
#!/bin/bash
# Run multiple tests in parallel for faster bisection

# Run tests in parallel
parallel --halt soon,fail=1 ::: \
    "pytest tests/unit/" \
    "pytest tests/integration/" \
    "npm run lint"

if [ $? -eq 0 ]; then
    echo "GOOD: All tests passed"
    exit 0
else
    echo "BAD: At least one test failed"
    exit 1
fi
State Preservation
bash
#!/bin/bash
# Preserve state between bisect steps

STATE_DIR=".bisect_state"
mkdir -p $STATE_DIR

# Save current commit info
git rev-parse HEAD > $STATE_DIR/current_commit

# Run test
./run_test
RESULT=$?

# Log result
echo "$(git rev-parse --short HEAD): $RESULT" >> $STATE_DIR/results.log

exit $RESULT

Troubleshooting

Issue: Bisect Marks Wrong Commit

Cause: Test script has incorrect exit codes or flaky behavior

Solution: Add verbose logging and retry logic

bash
set -x  # Enable debug output
# Add retry logic as shown in section 3
Show full SKILL.md (146 more words)Show less
Issue: Too Many Commits Skipped

Cause: Build failures or missing dependencies across history

Solution: Use broader skip conditions

bash
# Skip commits with known issues
if git log -1 --format=%s | grep -q "WIP\|broken"; then
    echo "SKIP: Known broken commit"
    exit 125
fi
Issue: Bisect Takes Too Long

Cause: Slow test execution

Solution: Optimize test or use binary search hints

bash
# Use timeout to fail fast
timeout 10s ./run_test || exit 125

# Or provide bisect hints
git bisect skip $(git rev-list --grep="refactor" HEAD~50..HEAD)

Best Practices

  1. Make tests deterministic: Fix random seeds, timestamps, and external dependencies
  2. Use timeouts: Prevent hanging tests from blocking bisect
  3. Log everything: Save detailed logs for each tested commit
  4. Handle build failures gracefully: Use exit code 125 to skip untestable commits
  5. Test the test script: Verify it works on known good and bad commits before bisecting
  6. Keep it fast: Optimize tests to run quickly (bisect tests O(log n) commits)

Quick Reference

Start bisect:

bash
git bisect start
git bisect bad <bad-commit>
git bisect good <good-commit>

Run automated bisect:

bash
git bisect run ./bisect_test.sh

Manual bisect:

bash
git bisect good  # Current commit is good
git bisect bad   # Current commit is bad
git bisect skip  # Cannot test current commit

End bisect:

bash
git bisect reset

Resources

© ArabelaTso, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 4 other files (scripts, references) in skills/bisect-aware-instrumentation of ArabelaTso/Skills-4-SE.

  • SKILL.md
  • references/exit_codes.md
  • references/git_bisect_guide.md
  • scripts/bisect_template.sh
  • scripts/bisect_wrapper.py

Open the folder on GitHubat commit 4f38503

Compare with similar skills

Bisect Aware Instrumentation next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Bisect Aware Instrumentation compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Bisect Aware Instrumentation this skillArabelaTso/Skills-4-SE253—~2kAutomated safety check: PassApache-2.0
Make Git Escrowinternet-court/internet-court-skill6.5k1 repos~922Automated safety check: NotesMIT
TiDB Test Diff Triagepingcap/tidb41k—~498Automated safety check: PassApache-2.0
Git Upstream Syncwado-lang/wado117—~855Automated safety check: PassMIT
SkillhoneTencent/SkillHone168—~3.4kAutomated safety check: PassCustom licence
Flowfile Failure ArchaeologyEdwardvaneechoud/Flowfile375—~7.5kAutomated safety check: PassMIT

Similar skills

  • Make Git Escrow

    internet-court/internet-court-skill

    Create a new git escrow bounty for a test suite. An agent skill from internet-court/internet-court-skill.

    6.5k GitHub starsUsed in 1 repo~922 tokens
    Testing & QAAuto-check: notes
  • Investigates TiDB plan or test-result diffs that the change does not explain, ruling out failpoint setup and merge effects before expected outputs are updated.

    41k GitHub stars~498 tokensUpdated today
    Testing & QAAuto-check passed
  • Git Upstream Sync

    wado-lang/wado

    The only way to merge origin/main into a branch, conflicts or not.

    117 GitHub stars~855 tokensUpdated today
    DevelopmentAuto-check passed
  • Skillhone

    Tencent/SkillHone

    Local Issue, pull-request, and Wiki workbench for agent skills.

    168 GitHub stars~3.4k tokensUpdated 20 days ago
    DevelopmentAuto-check passed
  • Flowfile Failure Archaeology

    Edwardvaneechoud/Flowfile

    Chronicles 25+ major incidents in Flowfile's git history (worker/kernel deadlocks and races, reverted or self-reverted branches, Electron/Tauri packaging breakage, codegen correctness bugs, CI…

    375 GitHub stars~7.5k tokensUpdated today
    DevelopmentAuto-check passed
  • Diagnose a Red Run

    different-ai/openwork

    Classifies a failing test, typecheck or CI job before any code changes, by recording the failure and running a clean control to show whether it was already broken.

    24k GitHub stars~779 tokensUpdated today
    Testing & QAAuto-check passed

More from ArabelaTso/Skills-4-SE

All 170 skills in this repo
  • Framework Migration Assistant

    ArabelaTso/Skills-4-SE

    Automatically migrate Python web applications between frameworks (Flask → FastAPI, Django → FastAPI).

    253 GitHub stars~1.9k tokensUpdated 1 mo ago
    Auto-check passed
  • Metamorphic Test Generator

    ArabelaTso/Skills-4-SE

    Generate test cases using metamorphic testing by applying transformations based on metamorphic properties.

    253 GitHub stars~798 tokensUpdated 1 mo ago
    Auto-check passed
  • Reproduction Trace Instrumenter

    ArabelaTso/Skills-4-SE

    Instruments programs to capture execution traces specifically for reproducing reported bugs, enabling consistent replay and diagnosis of failures.

    253 GitHub stars~2.4k tokensUpdated 1 mo ago
    Auto-check passed
  • Spring Mvc To Boot Migrator

    ArabelaTso/Skills-4-SE

    Automatically migrate Spring MVC applications to Spring Boot.

    253 GitHub stars~2.2k tokensUpdated 1 mo ago
    Auto-check passed
  • State Snapshot Instrumenter

    ArabelaTso/Skills-4-SE

    Instrument programs (Python, C/C++, Java) to capture snapshots of key program states at runtime, including variables, memory, and call stacks.

    253 GitHub stars~2.2k tokensUpdated 1 mo ago
    Auto-check passed

Works with

Questions about Bisect Aware Instrumentation

What does Bisect Aware Instrumentation do?

Instrument code to support efficient git bisect by producing deterministic pass/fail signals and concise runtime summaries for each tested commit. Bisect Aware Instrumentation is an agent skill from ArabelaTso/Skills-4-SE. Instrument code to support efficient git bisect by producing deterministic pass/fail signals and concise runtime summaries for each tested commit.

When should I use Bisect Aware Instrumentation?

Bisect Aware Instrumentation fits situations like: debugging regressions with git bisect; automating bisect workflows; creating bisect test scripts; handling flaky tests during bisection.

How do I install Bisect Aware Instrumentation in Claude Code?

Run `npx skills add ArabelaTso/Skills-4-SE --skill bisect-aware-instrumentation -a claude-code`. Or copy the skill folder (skills/bisect-aware-instrumentation in ArabelaTso/Skills-4-SE) into .claude/skills/bisect-aware-instrumentation in your project. Claude Code loads it when a task matches its description.

How do I install Bisect Aware Instrumentation in Codex?

Run `npx skills add ArabelaTso/Skills-4-SE --skill bisect-aware-instrumentation -a codex`. Or copy the skill folder (skills/bisect-aware-instrumentation in ArabelaTso/Skills-4-SE) into .agents/skills/bisect-aware-instrumentation in your project. Codex loads it when a task matches its description.

Can I use Bisect Aware Instrumentation in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add ArabelaTso/Skills-4-SE --skill bisect-aware-instrumentation -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/bisect-aware-instrumentation, .gemini/skills/bisect-aware-instrumentation, .github/skills/bisect-aware-instrumentation and .opencode/skills/bisect-aware-instrumentation in your project.

What does Bisect Aware Instrumentation need to run?

Going by SKILL.md and its folder, Bisect Aware Instrumentation needs a shell and Python for the scripts in its folder and the command-line tools its instructions call (git, npm and make). Our summary lists: Python 3; Node.js; A Bash shell.

Does Bisect Aware Instrumentation access the network?

SKILL.md contains no URLs. Its commands use git and npm, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Bisect Aware Instrumentation safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Bisect Aware Instrumentation use?

Bisect Aware Instrumentation is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Bisect Aware Instrumentation use?

About 2k tokens (SKILL.md is roughly 8.2k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 4.3k tokens, read only when the agent opens those files.

What are the alternatives to Bisect Aware Instrumentation?

Skills that share tags, products or a category with Bisect Aware Instrumentation: Make Git Escrow (internet-court/internet-court-skill, 6.5k stars), TiDB Test Diff Triage (pingcap/tidb, 41k stars), Git Upstream Sync (wado-lang/wado, 117 stars) and Skillhone (Tencent/SkillHone, 168 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Bisect Aware Instrumentation?

ArabelaTso (a GitHub user) maintains it in ArabelaTso/Skills-4-SE, which has 253 GitHub stars. The repository holds 170 skills in this directory. The repository was last updated on August 21, 2026.

Source: ArabelaTso/Skills-4-SE on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.