| name | git-xray |
| description | Run diagnostic git commands to assess a codebase's health before reading any code. Use this skill whenever the user asks you to understand a new codebase, audit a repo, assess technical debt, find risky code, check project health, figure out where to start reading, identify bus factor risks, or explore an unfamiliar repository. Also use it when the user asks 'what's going on in this repo', 'where are the problem areas', 'give me a health check', or 'what should I look at first'. If the user wants to understand a codebase at a strategic level before diving into code, this is the skill to use. |
Git X-Ray
Before reading a single line of code, run five diagnostic git commands to build a strategic picture of the repository. These commands reveal which files are hotspots, who built what, where bugs cluster, whether the project has momentum, and how often the team is firefighting. The whole process takes under a minute and transforms your initial exploration from random wandering into targeted investigation.
This approach is based on the insight that commit history is a behavioral record of a codebase — it tells you what actually happened, not what the architecture docs claim happened.
Inspired by: Five git commands that tell you where a codebase hurts before you open a single file by Ally Piechowski.
The Diagnostic Sequence
Run these five commands in order. Each builds on the picture from the previous ones.
1. What Changes the Most (Churn Analysis)
git log --format=format: --name-only --since="1 year ago" | sort | uniq -c | sort -nr | head -20
This surfaces the 20 most-modified files in the past year. High-churn files often indicate areas people are afraid to touch properly — they keep getting patched rather than fixed. A 2005 Microsoft Research study found that churn-based metrics predicted defects more reliably than complexity metrics.
