# Codebase Recon

> >

- **Type:** Skill
- **Install:** `agentstack add skill-yujiachen-y-codebase-recon-skill-codebase-recon`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [yujiachen-y](https://agentstack.voostack.com/s/yujiachen-y)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [yujiachen-y](https://github.com/yujiachen-y)
- **Source:** https://github.com/yujiachen-y/codebase-recon-skill/tree/main/skills/codebase-recon

## Install

```sh
agentstack add skill-yujiachen-y-codebase-recon-skill-codebase-recon
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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"](https://piechowski.io/post/git-commands-before-reading-code/) by [Ally Piechowski](https://github.com/grepsedawk).

## 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:

```sh
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:

```sh
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:

```sh
git shortlog -sn --no-merges
```

### 2c. Bug Magnets

Files most associated with bug-fix commits:

```sh
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):

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

### 2e. Firefighting Frequency

Emergency/revert commits in the analysis window:

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

### 2f. Recently Added Files

New files added in the analysis window:

```sh
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"):

```sh
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](https://github.com/yujiachen-y)
- **Source:** [yujiachen-y/codebase-recon-skill](https://github.com/yujiachen-y/codebase-recon-skill)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-yujiachen-y-codebase-recon-skill-codebase-recon
- Seller: https://agentstack.voostack.com/s/yujiachen-y
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.