repo-recon

Repo recon

The first structured pass over an unfamiliar system.

Why this exists

Dropped into a large codebase, the instinct is to start reading. After two hours you know one component and cannot answer the questions people are about to ask. This skill trades depth for coverage: where things are and what you'd be scared to touch. Depth is trace-the-flow, later, only where the work lands. A map that exists only in this session is worthless in week three.

When this applies

• Any unfamiliar codebase you'll work in for more than a day
• Before estimating, designing, or changing anything
• Inheriting a system whose authors have left
• Someone asks what a repository does and you don't know

When it doesn't

• You already know the system — read CLAUDE.md and go
• You need one specific fact — grep for it
• The repository is small enough to read outright (under ~500 files)
• You need deep behavior of a single flow — that's trace-the-flow

Prerequisites

• Locate the workspace (../_shared/workspace-conventions.md)
• 00-engagement.md — scopes what you're looking for
• 00c-context.md / 01-environment.md (optional) — budget and whether it builds
• Read ../_shared/stack-detection.md before step 2, including Searching after detection
• On anything over ~5,000 files, apply context-strategy first and set a budget

Procedure

Ordered cheapest to most expensive. Each step should sharpen where the next one looks. Read the stopping test in step 10 before you start — it's what stops this becoming a week.

1. Shape

git ls-files | wc -l
git ls-files | sed 's/.*\.//' | tr '[:upper:]' '[:lower:]' | sort | uniq -c | sort -rn | head -20
ls -a
find . -maxdepth 2 -type d -not -path "*/.git*" -not -path "*/node_modules*" | sort
git log -1 --format="%ad %an" --date=short
git log --oneline --since="6 months ago" | wc -l

You're establishing: how big, what languages, is it alive, is it one system or several. A repository with three commits in six months and a top language you didn't expect is telling you something before you read a line.