skill-codebase-recon

name	skill-codebase-recon
description	Git forensics analyst for identifying hotspots, logic churn, and knowledge gaps via commit history.

Codebase Reconnaissance: Git Forensics Protocol

Before diving into the source code, use these Git forensics to identify hotspots, risks, and institutional knowledge gaps. These commands help build a mental map of "danger zones" and key contributors.

1. Identify Churn (The "Danger Zones")

Goal: Find the 20 most-frequently changed files in the last year. High churn indicates active development or a "God Object."

git log --format=format: --name-only --since="1 year ago" | sort | uniq -c | sort -nr | head -20

Interpretation: If the top files are also technical debt items, they are major drivers of "codebase drag."

2. Evaluate the "Bus Factor"

Goal: Identify who built the system and check if they are still active.

• Overall Contributors: git shortlog -sn --no-merges
• Active Contributors (Last 6 Months): git shortlog -sn --no-merges --since="6 months ago" Interpretation: If one person has >60% of commits, the Bus Factor is high. If top contributors are absent from the 6-month list, knowledge has left the building.

3. Locate Bug Hotspots

Goal: Find where "fixes" are concentrated. Files constantly being fixed are likely fragile.

git log --format=format: --name-only --grep="fix\|bug\|broken" | sort | uniq -c | sort -nr | head -20

Interpretation: Cross-reference this with the Churn list. A file that is both high-churn and high-bug is a primary stability risk.

4. Gauge Project Velocity

Goal: Determine if the project is accelerating, stable, or dying by looking at yearly commit volume.

git log --date=format:"%Y-%m" --format="%ad" | sort | uniq -c

Interpretation: A steady decline may indicate maintenance mode. Sudden spikes followed by silence may suggest high-pressure firefighting.

5. Detect Crisis Patterns (Firefighting)

Goal: Find how often the team has to revert or hotfix.

git log --oneline --since="1 year ago" --grep="revert\|hotfix\|emergency\|rollback"

Interpretation: A long list suggests skipping QA or immense pressure to deploy, leading to a "patch-on-a-patch" culture.

Usage Guidelines

• Merge Strategy: If the team uses Squash Merges, authorship reflects the merger rather than the individual authors. Verify the merge strategy first.
• Context: Use these commands as a "first-look" before running static analysis or deep-dive code reviews.