Codebase Recon

Codebase Recon

Analyze git history to understand a codebase before reading any code. Reveals project health, risk areas, team structure, and development momentum.

Inspired by "The Git Commands I Run Before Reading Any Code" by Ally Piechowski.

Phase 1: Probe

Before running analysis, determine repo scale to calibrate time windows and result counts.

Run this single shell command to collect repo vitals:

echo "COMMITS=$(git rev-list --count HEAD)" && \
echo "FIRST_COMMIT=$(git log --reverse --format='%ad' --date=short | head -1)" && \
echo "LATEST_COMMIT=$(git log --format='%ad' --date=short | head -1)" && \
echo "BRANCHES=$(git branch -a | wc -l | tr -d ' ')"

Use the commit count to set parameters for Phase 2:

| Repo Size | Commits | WINDOW (--since) | N (--head) | |-----------|---------|---------------------|--------------| | Small | 10k | 6 months ago | 30 |

Print the Repo Vitals line immediately:

Repo Vitals: Age: [FIRST_COMMIT to LATEST_COMMIT] | Commits: [COMMITS] | Branches: [BRANCHES] | Analysis window: [WINDOW or "all time"]

Phase 2: Parallel Analysis

Run all 7 commands in parallel (they are independent). Substitute WINDOW and N from Phase 1. For small repos, omit --since flags entirely.

2a. Code Hotspots

Most-changed files in the analysis window:

git log --format=format: --name-only --since="WINDOW" | sort | uniq -c | sort -nr | head -N

2b. Bus Factor

All-time contributor ranking by commit count:

git shortlog -sn --no-merges

2c. Bug Magnets

Files most associated with bug-fix commits:

git log -i -E --grep="fix|bug|broken" --name-only --format='' --since="WINDOW" | sort | uniq -c | sort -nr | head -N

2d. Team Momentum

Commit frequency by month (all time):

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

2e. Firefighting Frequency

Emergency/revert commits in the analysis window:

git log --oneline --since="WINDOW" | grep -iE 'revert|hotfix|emergency|rollback'

2f. Recently Added Files

New files added in the analysis window:

git log --diff-filter=A --since="WINDOW" --name-only --format='' | sort | uniq -c | sort -nr | head -N

2g. Active vs Total Contributors

Count of contributors active in the last 3 months (fixed window — measures "who's here now"):

git shortlog -sn --no-merges --since="3 months ago" | wc -l

Compare this count against the total from 2b.

Cross-Referencing

After collecting all Phase 2 results, perform these cross-references before presenting the report:

1. High-Risk Files: Intersect code hotspots (2a) with bug magnets (2c). Files appearing in both lists are highest-risk.
2. Risk Ownership: For each high-risk file, run git shortlog -sn -- to identify the primary owner.
3. Bus Factor Risk: If active contributors (2g) are less than 30% of total contributors (2b), flag this as a bus factor concern.
4. Momentum Trend: Analyze the monthly commit counts (2d):

• Compare the average of the last 3 months to the average of the 3 months before that.
• Rising: last 3 months average > prior 3 months average by 20%+
• Declining: last 3 months average "Want me to save this report to a markdown file? (e.g., docs/codebase-recon-report.md)"

If yes, write the same content as a markdown file. Do not commit — let the user decide.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yujiachen-y
• Source: yujiachen-y/codebase-recon-skill
• License: MIT

Install and usage instructions live in the source repository linked above.