codebase-recon
Use when entering an unfamiliar codebase, onboarding to a new project, or wanting to assess codebase health before reading code — analyzes git history to reveal hotspots, risk areas, team structure, and development momentum
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- codebase-recon
- metadata
- { "author": "yujiachen-y", "version": "1.0", "inspired-by": "https://piechowski.io/post/git-commands-before-reading-code/" }
- description
- Use when entering an unfamiliar codebase, onboarding to a new project, or wanting to assess codebase health before reading code — analyzes git history to reveal hotspots, risk areas, team structure, and development momentum
- compatibility
- Requires git. Works in any terminal-based coding agent.
03 SKILL.md 正文
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 | <500 | (omit --since) | 10 |
| Medium | 500-10k | 1 year ago |
20 |
| Large | >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:
- High-Risk Files: Intersect code hotspots (2a) with bug magnets (2c). Files appearing in both lists are highest-risk.
- Risk Ownership: For each high-risk file, run
git shortlog -sn -- <file>to identify the primary owner. - Bus Factor Risk: If active contributors (2g) are less than 30% of total contributors (2b), flag this as a bus factor concern.
- 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 < prior 3 months average by 20%+
- Erratic: month-over-month variance exceeds 50%
- Stable: otherwise
Report Template
Present the report in the terminal using this structure:
═══ Codebase Recon Report ═══
Repo Vitals
Age: [first commit] to [latest commit] | Commits: N | Branches: N | Analysis window: WINDOW
1. Code Hotspots (most-changed files)
[ranked list: count filepath]
2. Bug Magnets (files with fix/bug/broken commits)
[ranked list: count filepath]
3. High-Risk Files (appear in BOTH hotspots AND bug magnets)
[list with: filepath — hotspot rank #X, bug magnet rank #Y, primary owner: NAME]
If none overlap, state: "No files appear in both lists — good sign."
4. Bus Factor
[top 10 contributors: count name]
Active (last 3 months): X of Y total contributors
[If active < 30% of total: "Warning: low active contributor ratio — knowledge concentration risk"]
5. Team Momentum
[monthly commit counts, most recent 12 months or all if fewer]
Trend: [rising / stable / declining / erratic]
6. Firefighting Frequency
[list of revert/hotfix/emergency commits, or "None found"]
Rate: N emergency commits out of M total in window (X%)
7. Recently Added Files
[ranked list: count filepath]
8. Recommendations
- Start reading: [top 3 high-risk files, or top 3 hotspots if no high-risk files]
- Talk to: [primary owner of the #1 high-risk or hotspot file]
- Watch out: [any trend warnings — declining momentum, low bus factor, high firefighting rate]
After printing the report, ask:
"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.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.