Git History Forensics

When code behavior changes without a corresponding ticket or explanation, memory and guesswork are poor substitutes for evidence. This skill treats a Git repository as a forensic record to answer why a specific line exists or when a regression actually started. It moves beyond simple blame to analyze commit context, file coupling, and churn to provide a verifiable history of changes.

What it does

• Line forensics blames specific lines and follows their history through renames to find the original intent.
• Churn analysis ranks files by insertions, deletions, and commit frequency to identify high-activity areas.
• Logical coupling identifies files that frequently change together, revealing the hidden blast radius of a change.
• Regression bounding calculates the commit window between known good and bad states to automate bisecting.
• Forensic reporting generates structured, blameless notes that anchor every finding to a SHA and a date.

How it works

1. Locate the change using when to trace a line or hot to find where the most activity occurred.
2. Analyze context by comparing the author's claims in the commit message against the actual changes in the patch.
3. Identify coupling with the couple command to see which files act as traveling companions to the suspect path.
4. Execute the hunt by defining a deciding check command and generating a git bisect driver.
5. Document findings using the note command to record evidence and findings in a standardized format.

Frameworks & tools

This tool uses a Python 3 CLI script gitarch.py that interacts with the local Git binary. It requires no network access and relies solely on the standard library and local repository history.

Why this beats prompting it yourself

Generic LLM prompts often hallucinate commit history or fail to track files across complex renames. This skill uses a specialized script to pull raw evidence directly from your local repo, ensuring every claim is backed by a real SHA and timestamp rather than a guess.

Use cases

• Investigating a changed default value or flag that has no associated Jira ticket.
• Mapping the blast radius of a subsystem rewrite by identifying coupled files.
• Finding the exact commit that introduced a regression in a large monorepo.
• Generating audit-ready documentation for postmortems or vendor questionnaires.

Known limitations

Renames rewritten below Git's detection threshold or directory-level renames may break the history chain. Squashed or rebased history can hide intermediate states and original timestamps.