/codebase-audit

name: codebase-audit
# Source: https://piechowski.io/post/git-commands-before-reading-code/
description: >
  Analyze a git repo's history to surface high-churn files, ownership risks, bug
  hotspots, momentum trends, and firefighting patterns. Use this skill whenever
  the user wants to understand a codebase, assess repo health, or orient
  themselves before reading code — even if they don't explicitly say "audit".
  Examples: "audit this repo", "analyze this repo's history", "what's the state
  of this codebase?", "bus factor", "churn analysis", "tell me about this repo",
  "who owns this code?", "is this repo healthy?".
allowed-tools:
  - Bash
context: fork

Codebase Audit

Analyze the current git repository's history to produce a structured health report covering churn, ownership, bugs, momentum, and firefighting patterns.

Goal

Produce a structured markdown report with one section per dimension, including raw data (top files/contributors) and observations. The report should help the reader orient themselves in an unfamiliar codebase and identify risk areas before reading code.

Steps

Steps 1a-1e are independent — run them in parallel, then synthesize in step 2.

0. Detect GitHub availability

Before starting the analysis, check whether the repo is GitHub-hosted and `gh` is authenticated:

gh repo view --json nameWithOwner 2>/dev/null

If this succeeds, set a mental flag that GitHub enrichments are available. If it fails (not a GitHub repo, or `gh` not authenticated), skip all `gh`-prefixed sub-steps below and rely on git-only analysis. Do not warn or apologize — just use what's available.

1a. High-Churn Files

1a-i. Raw churn

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

Report the top 20 most-modified files in the past year. Flag any file that appears disproportionately often -- this is the clearest signal of codebase drag.

1a-ii. De-noised churn

Lockfiles, generated output and vendored trees dominate raw churn without telling you anything about the code. If 5 or more of the top 10 are noise of this kind, run a filtered second pass:

NOISE='(^|/)([^/]*-lock\.(json|yaml)|[^/]*\.lock|package\.json|go\.sum|CHANGELOG\.md|[^/]*\.snap)$|(^|/)(__snapshots__|dist|build|coverage|generated|vendor|node_modules|\.terraform)/'
git log --format=format: --name-only --since="1 year ago" | grep . | grep -vE "$NOISE" | sort | uniq -c | sort -nr | head -20

Extend `$NOISE` with repo-specific paths when the filtered pass is still dominated by bulk content (`docs/`, `locales/`, `i18n/`). Label that as a repo-specific pass, separate from the generic de-noising above.

Report both passes and name what was excluded — a lockfile churning 80 times is itself a finding about dependency pressure, it just isn't a finding about the code.

Keep the blank-line strip as its own `grep .` rather than folding `^$` into `$NOISE`. BSD grep (macOS) drops the `^$` branch when the alternation contains a leading `.*`, silently leaving every blank line in the count.

1a-iii. Directory-level triage

When file-level hotspots are too noisy to read — large repos, monorepos:

git log --format=format: --name-only --since="1 year ago" | grep . | cut -d/ -f1-2 | sort | uniq -c | sort -nr | head -20

1b. Team Ownership / Bus Factor

Commit count alone is a poor proxy for ownership. Someone reformatting config files 100 times looks more "important" than someone who architected a core subsystem in 5 commits. Gather multiple signals to build a nuanced picture.

1b-i. Commit counts (all-time vs recent)

git shortlog -sn --no-merges

git shortlog -sn --no-merges --since="6 months ago"

Under a squash-merge workflow these counts reflect who *merged*, not who wrote the code — which can invert the ranking entirely. Check before trusting it:

gh pr list --state merged --limit 20 --json mergeCommit,author

If GitHub is unavailable, a history of single-commit merges with no branch topology is the tell.

1b-ii. Lines changed per author

For the top 5 contributors by commit count, measure insertions and deletions:

git log --author="<name>" --numstat --no-merges --format='' | awk '{ add += $1; del += $2 } END { print "+" add, "-" del }'

This distinguishes high-volume contributors from high-frequency ones.

1b-iii. Subsystem ownership

Identify the top-level directories in the repo, then for each one show the top 3 contributors:

git shortlog -sn --no-merges -- <directory>

This reveals domain expertise — one person may own 80% of `infra/` while another owns `src/auth/`. Concentrated subsystem ownership is a bus-factor risk even when overall commit counts look balanced.

1b-iv. Commit sampling

For each of the top 3 contributors, sample their 5 most recent commits:

git log --author="<name>" --no-merges --oneline -5

Use the commit messages to characterize the nature of their work: features, bug fixes, refactoring, formatting, dependency updates, etc. This adds qualitative context that numbers alone cannot provide.

1b-v. (gh) PR review patterns

Only if GitHub is available. Query merged PRs to understand who reviews whose code:

gh pr list --state merged --limit 100 --json author,reviews

Look for review silos — if only one person reviews a particular author's PRs, that's a knowledge concentration risk. Also note if anyone is a "review bottleneck" (appears as reviewer on most PRs).

1b-vi. (gh) GitHub contributor stats

Only if GitHub is available. GitHub's own contributor statistics include weekly additions/deletions per author, which is more efficient than looping `git log --numstat` per author:

gh api repos/{owner}/{repo}/stats/contributors

Use this to cross-validate the git-based lines-changed data from 1b-ii. If available, prefer this data as it's pre-aggregate