| name | navvy |
| description | Diagnose a codebase through its git history before reading any code. Surfaces churn hotspots, bus factor risks, bug clusters, velocity trends, and firefighting patterns. Only invoked directly via /navvy — does not auto-trigger.
|
Navvy
Five git commands, run in under a minute, that tell you more about a codebase than an hour of reading code. Commit history is diagnostic data — it reveals team dynamics, risk concentration, and maintenance patterns that the code itself cannot.
Run all five commands, then synthesize the results into a diagnostic report.
The Commands
Run these in parallel where possible. Adjust --since to match the project's age — use 1 year ago for active projects, extend for slower-moving ones.
1. Churn hotspots
git log --format=format: --name-only --since="1 year ago" | sort | uniq -c | sort -nr | head -20
The 20 most-modified files in the past year. High churn on a file that nobody wants to own is the clearest signal of codebase drag — these files have unpredictable blast radius and inflate estimates.
2. Contributor map
git shortlog -sn --no-merges
Ranks contributors by commit count. Look for bus factor risk: if one person accounts for 60%+ of commits, knowledge is dangerously concentrated. Also check whether core contributors are still active.
3. Bug clusters
git log -i -E --grep="fix|bug|broken" --name-only --format='' | sort | uniq -c | sort -nr | head -20
Files most frequently touched in bug-related commits. Files appearing in both this list and the churn hotspots are highest-risk code — they keep breaking and keep getting patched.
4. Velocity trend
git log --format='%ad' --date=format:'%Y-%m' | sort | uniq -c
Commit counts by month across the full history. A steady rhythm is healthy. Sharp declines suggest departures or loss of momentum. Sporadic spikes suggest batched releases rather than continuous delivery.
5. Firefighting signals
git log --oneline --since="1 year ago" | grep -iE 'revert|hotfix|emergency|rollback'
Reverts and hotfixes. Frequent occurrences signal the team doesn't trust its deploy process — a symptom of deeper issues with testing or deployment reliability.
Synthesizing the Report
After running all five commands, write a short diagnostic report. Structure it around what the data reveals, not around the commands themselves.
What to look for
- Overlap between churn and bugs. Files appearing in both lists are the highest-leverage targets for refactoring or better test coverage.
- Bus factor. A single dominant contributor who's gone inactive is a risk. A well-distributed contributor map is healthy.
- Velocity shifts. Correlate drops or spikes with what you know about the project — team changes, rewrites, launches.
- Firefighting frequency. A few reverts a year is normal. Monthly hotfixes suggest systemic issues.
Report format
# Codebase Diagnostic: [repo name]
## Key Findings
[2-4 bullet points: the most important things to know before touching this code]
## Churn Hotspots
[Top files, what they are, whether they overlap with bug clusters]
## Team & Ownership
[Bus factor assessment, active vs inactive contributors]
## Health Signals
[Velocity trend interpretation, firefighting frequency]
## Recommendations
[Where to focus attention, what to investigate further]
Keep it concise. The point is orientation, not exhaustive analysis. A reader should finish the report knowing where the bodies are buried and where to tread carefully.
