Repo Inspection Manual

Use this whenever you open an unfamiliar repository. The goal is to build a map before making changes.

Mental Model

A repo is not the system. A repo is the instruction manual, parts list, and build recipe for a system. The running system also needs runtime, configuration, secrets, data, network, infrastructure, and users.

First 15 Minutes

Run or inspect:

pwd
find . -maxdepth 2 -type f | sort | sed 's#^\./##'
git status --short --branch
git log --oneline -5

Then answer:

What language or framework is this?
What starts the app?
What installs dependencies?
What runs tests?
What builds an artifact?
Where is configuration read?
Where are secrets expected?
Where does data live?

Files That Usually Matter

File	What It Often Means
`package.json`	Node app scripts, dependencies, test/build commands
`pyproject.toml`	Python package, dependencies, tooling
`requirements.txt`	Python dependencies
`Dockerfile`	Container build recipe
`docker-compose.yml`	Local multi-service runtime
`.env.example`	Required environment variables
`README.md`	Human operating notes
`Makefile`	Common command shortcuts
`.github/workflows/*`	CI/CD behavior
`migrations/*`	Database schema history
`src`, `app`, `server`, `services`	Likely implementation roots

Trace The Runtime

Draw this:

command -> entry file -> route/controller -> service -> database/external API

Example:

npm run dev
  -> src/main.tsx
  -> src/pages/Tickets.tsx
  -> src/api/tickets.ts
  -> POST /api/tickets
  -> server/routes/tickets.ts
  -> ticketService.create()
  -> database tickets table

Inspection Questions

What is the smallest feature I can trace end to end?
What code is user-facing?
What code is trusted server-side?
What code is background work?
Where is validation done?
Where are errors handled?
What tests already exist?
What breaks if the database is empty?
What breaks if an external API is down?

Output Artifact

Create repo-map.md:

# Repo Map

## Purpose

## Tech Stack

## Start Commands

## Main Entry Points

## Feature Flow

## Data Stores

## External Services

## Tests

## Deployment Path

## Unknowns

Done When

Another engineer can read your map and know where to start changing one feature.