Summary

Investigate the project history to find when regressions or behavioral changes were introduced. Use targeted git queries, commit bisects, and contextual diffs to identify the minimal change that caused a failure.

Objectives

• Locate the commit that introduced a regression quickly
• Extract the minimal diff that explains behavior change
• Provide reproducible test cases tied to specific commits
• Produce safe rollback or fix guidance based on git evidence

Principles

1. Use git history as a forensic tool—relevant commits contain the best clues.

2. Reproduce the issue at specific commits to confirm causality.

3. Prefer bisect-driven isolation over manual guesswork.

4. Preserve history; use branch-based fixes and clear commit messages for rollbacks.

Implementation Pattern

Step 1 — Identify the approximate time window or feature area

• Collect error timestamps, release notes, and deploy events.
• Map failing behavior to likely touched files or subsystems.

Step 2 — Run a focused git log and file blame

• Use git log -- path to see recent changes to related files.
• Use git blame to find when the specific line was last changed and by whom.

Step 3 — Create a reproducible test for the failing behavior

• Capture a small test or harness that fails on the current main branch.
• Confirm the test passes on an earlier known-good commit if available.

Step 4 — Use git bisect to isolate the offending commit

• Start bisect with known-good and known-bad commits.
• Automate test runs during bisect to let git find the exact commit quickly.

Step 5 — Analyze the diff and add targeted fixes or revert where necessary

• Review the minimal diff to understand intent and side effects.
• If a quick revert is safe, prepare a revert PR with explanation.
• Otherwise craft a minimal patch that preserves intent and fixes the bug.

Anti-Pattern (Before)

Manually scanning thousands of commits or reverting broad ranges without confirming behavior at each step.

Recommended Pattern (After)

Use bisect and test harness:

'# Example commands

git bisect start

git bisect bad HEAD

git bisect good v1.4.2

let bisect run tests and identify offending commit'

Benefits:

• Precise identification of the breaking change.
• Clear audit trail for decisions and rollbacks.
• Faster remediation with minimal collateral risk.

Best Practices

• Always include a reproducible test before bisecting.
• Record environment and dependency versions when reproducing historical commits.
• Prefer targeted fixes over blind reverts.
• Annotate the discovered commit with a follow-up issue and remediation plan.

Agent Prompts

"Run git log for the files touched by this failure and summarize likely suspects."

"Automate git bisect using this test script and report the first bad commit."

"Show the diff between the last good and first bad commits and highlight risky changes."

Notes

• When bisecting across major refactors, bisect may land on commits requiring build or dependency changes; handle these as special cases.
• Keep test harness lightweight so bisect can run quickly in CI.