codebase-recon

Name: codebase-recon
Author: yujiachen-y

107installs1forks

How to install codebase-recon?

yujiachen-y/codebase-recon-skill/codebase-recon

$npx -y skills add yujiachen-y/codebase-recon-skill --skill codebase-recon

Installs into the current project.

Summary

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

Files · 1

View on GitHub

SKILL.md

1	# Codebase Recon
2
3	Analyze git history to understand a codebase before reading any code. Reveals project health, risk areas, team structure, and development momentum.
4
5	Inspired by ["The Git Commands I Run Before Reading Any Code"](https://piechowski.io/post/git-commands-before-reading-code/) by [Ally Piechowski](https://github.com/grepsedawk).
6
7	## Phase 1: Probe
8
9	Before running analysis, determine repo scale to calibrate time windows and result counts.
10
11	Run this single shell command to collect repo vitals:
12
13	```sh
14	echo "COMMITS=$(git rev-list --count HEAD)" && \
15	echo "FIRST_COMMIT=$(git log --reverse --format='%ad' --date=short \| head -1)" && \
16	echo "LATEST_COMMIT=$(git log --format='%ad' --date=short \| head -1)" && \
17	echo "BRANCHES=$(git branch -a \| wc -l \| tr -d ' ')"
18	```
19
20	Use the commit count to set parameters for Phase 2:
21
22	\| Repo Size \| Commits \| `WINDOW` (--since) \| `N` (--head) \|
23	\|-----------\|---------\|---------------------\|--------------\|
24	\| Small \| <500 \| (omit --since) \| 10 \|
25	\| Medium \| 500-10k \| `1 year ago` \| 20 \|
26	\| Large \| >10k \| `6 months ago` \| 30 \|
27
28	Print the Repo Vitals line immediately:
29
30	```
31	Repo Vitals: Age: [FIRST_COMMIT to LATEST_COMMIT] \| Commits: [COMMITS] \| Branches: [BRANCHES] \| Analysis window: [WINDOW or "all time"]
32	```
33
34	## Phase 2: Parallel Analysis
35
36	Run all 7 commands in parallel (they are independent). Substitute `WINDOW` and `N` from Phase 1. For small repos, omit `--since` flags entirely.
37
38	### 2a. Code Hotspots
39
40	Most-changed files in the analysis window:
41
42	```sh
43	git log --format=format: --name-only --since="WINDOW" \| sort \| uniq -c \| sort -nr \| head -N
44	```
45
46	### 2b. Bus Factor
47
48	All-time contributor ranking by commit count:
49
50	```sh
51	git shortlog -sn --no-merges
52	```
53
54	### 2c. Bug Magnets
55
56	Files most associated with bug-fix commits:
57
58	```sh
59	git log -i -E --grep="fix\|bug\|broken" --name-only --format='' --since="WINDOW" \| sort \| uniq -c \| sort -nr \| head -N
60	```
61
62	### 2d. Team Momentum
63
64	Commit frequency by month (all time):
65
66	```sh
67	git log --format='%ad' --date=format:'%Y-%m' \| sort \| uniq -c
68	```
69
70	### 2e. Firefighting Frequency
71
72	Emergency/revert commits in the analysis window:
73
74	```sh
75	git log --oneline --since="WINDOW" \| grep -iE 'revert\|hotfix\|emergency\|rollback'
76	```
77
78	### 2f. Recently Added Files
79
80	New files added in the analysis window:
81
82	```sh
83	git log --diff-filter=A --since="WINDOW" --name-only --format='' \| sort \| uniq -c \| sort -nr \| head -N
84	```
85
86	### 2g. Active vs Total Contributors
87
88	Count of contributors active in the last 3 months (fixed window — measures "who's here now"):
89
90	```sh
91	git shortlog -sn --no-merges --since="3 months ago" \| wc -l
92	```
93
94	Compare this count against the total from 2b.
95
96	## Cross-Referencing
97
98	After collecting all Phase 2 results, perform these cross-references before presenting the report:
99
100	1. High-Risk Files: Intersect code hotspots (2a) with bug magnets (2c). Files appearing in both lists are highest-risk.
101	2. Risk Ownership: For each high-risk file, run `git shortlog -sn -- <file>` to identify the primary owner.
102	3. Bus Factor Risk: If active contributors (2g) are less than 30% of total contributors (2b), flag this as a bus factor concern.
103	4. Momentum Trend: Analyze the monthly commit counts (2d):
104	- Compare the average of the last 3 months to the average of the 3 months before that.
105	- Rising: last 3 months average > prior 3 months average by 20%+
106	- Declining: last 3 months average < prior 3 months average by 20%+
107	- Erratic: month-over-month variance exceeds 50%
108	- Stable: otherwise
109
110	## Report Template
111
112	Present the report in the terminal using this structure:
113
114	```
115	═══ Codebase Recon Report ═══
116
117	Repo Vitals
118	Age: [first commit] to [latest commit] \| Commits: N \| Branches: N \| Analysis window: WINDOW
119
120	1. Code Hotspots (most-changed files)
121	[ranked list: count filepath]
122
123	2. Bug Magnets (files with fix/bug/broken commits)
124	[ranked list: count filepath]
125
126	3. High-Risk Files (appear in BOTH hotspots AND bug magnets)
127	[list with: filepath — hotspot rank #X, bug magnet rank #Y, primary owner: NAME]
128	If none overlap, state: "No files appear in both lists — good sign."
129
130	4. Bus Factor
131	[top 10 contributors: count name]
132	Active (last 3 months): X of Y total contributors
133	[If active < 30% of total: "Warning: low active contributor ratio — knowledge concentration risk"]
134
135	5. Team Momentum
136	[monthly commit counts, most recent 12 months or all if fewer]
137	Trend: [rising / stable / declining / erratic]
138
139	6. Firef

People who liked this also viewed

6 picks

Type

codebase-recon

107installs1forks

View on GitHub

How to install codebase-recon?

yujiachen-y/codebase-recon-skill/codebase-recon

$npx -y skills add yujiachen-y/codebase-recon-skill --skill codebase-recon

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Codebase Recon
2
3	Analyze git history to understand a codebase before reading any code. Reveals project health, risk areas, team structure, and development momentum.
4
5	Inspired by ["The Git Commands I Run Before Reading Any Code"](https://piechowski.io/post/git-commands-before-reading-code/) by [Ally Piechowski](https://github.com/grepsedawk).
6
7	## Phase 1: Probe
8
9	Before running analysis, determine repo scale to calibrate time windows and result counts.
10
11	Run this single shell command to collect repo vitals:
12
13	```sh
14	echo "COMMITS=$(git rev-list --count HEAD)" && \
15	echo "FIRST_COMMIT=$(git log --reverse --format='%ad' --date=short \| head -1)" && \
16	echo "LATEST_COMMIT=$(git log --format='%ad' --date=short \| head -1)" && \
17	echo "BRANCHES=$(git branch -a \| wc -l \| tr -d ' ')"
18	```
19
20	Use the commit count to set parameters for Phase 2:
21
22	\| Repo Size \| Commits \| `WINDOW` (--since) \| `N` (--head) \|
23	\|-----------\|---------\|---------------------\|--------------\|
24	\| Small \| <500 \| (omit --since) \| 10 \|
25	\| Medium \| 500-10k \| `1 year ago` \| 20 \|
26	\| Large \| >10k \| `6 months ago` \| 30 \|
27
28	Print the Repo Vitals line immediately:
29
30	```
31	Repo Vitals: Age: [FIRST_COMMIT to LATEST_COMMIT] \| Commits: [COMMITS] \| Branches: [BRANCHES] \| Analysis window: [WINDOW or "all time"]
32	```
33
34	## Phase 2: Parallel Analysis
35
36	Run all 7 commands in parallel (they are independent). Substitute `WINDOW` and `N` from Phase 1. For small repos, omit `--since` flags entirely.
37
38	### 2a. Code Hotspots
39
40	Most-changed files in the analysis window:
41
42	```sh
43	git log --format=format: --name-only --since="WINDOW" \| sort \| uniq -c \| sort -nr \| head -N
44	```
45
46	### 2b. Bus Factor
47
48	All-time contributor ranking by commit count:
49
50	```sh
51	git shortlog -sn --no-merges
52	```
53
54	### 2c. Bug Magnets
55
56	Files most associated with bug-fix commits:
57
58	```sh
59	git log -i -E --grep="fix\|bug\|broken" --name-only --format='' --since="WINDOW" \| sort \| uniq -c \| sort -nr \| head -N
60	```
61
62	### 2d. Team Momentum
63
64	Commit frequency by month (all time):
65
66	```sh
67	git log --format='%ad' --date=format:'%Y-%m' \| sort \| uniq -c
68	```
69
70	### 2e. Firefighting Frequency
71
72	Emergency/revert commits in the analysis window:
73
74	```sh
75	git log --oneline --since="WINDOW" \| grep -iE 'revert\|hotfix\|emergency\|rollback'
76	```
77
78	### 2f. Recently Added Files
79
80	New files added in the analysis window:
81
82	```sh
83	git log --diff-filter=A --since="WINDOW" --name-only --format='' \| sort \| uniq -c \| sort -nr \| head -N
84	```
85
86	### 2g. Active vs Total Contributors
87
88	Count of contributors active in the last 3 months (fixed window — measures "who's here now"):
89
90	```sh
91	git shortlog -sn --no-merges --since="3 months ago" \| wc -l
92	```
93
94	Compare this count against the total from 2b.
95
96	## Cross-Referencing
97
98	After collecting all Phase 2 results, perform these cross-references before presenting the report:
99
100	1. High-Risk Files: Intersect code hotspots (2a) with bug magnets (2c). Files appearing in both lists are highest-risk.
101	2. Risk Ownership: For each high-risk file, run `git shortlog -sn -- <file>` to identify the primary owner.
102	3. Bus Factor Risk: If active contributors (2g) are less than 30% of total contributors (2b), flag this as a bus factor concern.
103	4. Momentum Trend: Analyze the monthly commit counts (2d):
104	- Compare the average of the last 3 months to the average of the 3 months before that.
105	- Rising: last 3 months average > prior 3 months average by 20%+
106	- Declining: last 3 months average < prior 3 months average by 20%+
107	- Erratic: month-over-month variance exceeds 50%
108	- Stable: otherwise
109
110	## Report Template
111
112	Present the report in the terminal using this structure:
113
114	```
115	═══ Codebase Recon Report ═══
116
117	Repo Vitals
118	Age: [first commit] to [latest commit] \| Commits: N \| Branches: N \| Analysis window: WINDOW
119
120	1. Code Hotspots (most-changed files)
121	[ranked list: count filepath]
122
123	2. Bug Magnets (files with fix/bug/broken commits)
124	[ranked list: count filepath]
125
126	3. High-Risk Files (appear in BOTH hotspots AND bug magnets)
127	[list with: filepath — hotspot rank #X, bug magnet rank #Y, primary owner: NAME]
128	If none overlap, state: "No files appear in both lists — good sign."
129
130	4. Bus Factor
131	[top 10 contributors: count name]
132	Active (last 3 months): X of Y total contributors
133	[If active < 30% of total: "Warning: low active contributor ratio — knowledge concentration risk"]
134
135	5. Team Momentum
136	[monthly commit counts, most recent 12 months or all if fewer]
137	Trend: [rising / stable / declining / erratic]
138
139	6. Firef

People who liked this also viewed

6 picks

Type