Repo Recon
Systematically map an unfamiliar codebase before changing anything. The recon
pass is a short, bounded sequence — minutes, not hours — that front-loads the
understanding you would otherwise pay for painfully later in broken builds,
rejected PRs, and rewrites. It is the "before" half of every safe edit.
Overview
Reconnaissance is cheap; guessing is expensive. Before you touch a single
line, spend a few minutes answering five questions:
- What is this repo and how is it laid out?
- How do I build, test, and run it?
- Where does one real flow live, and how does it work end-to-end?
- What conventions must my code match?
- Where did I write all of this down?
The five-step pass below answers them in order. The output is a written
recon note: a map, a command cheat-sheet, one traced flow, and a convention
list. That note is the deliverable — not code changes.
When to Use
Use this skill when:
- You are working in a repository for the first time.
- You are returning to a repo after a long absence (memory is stale).
- The codebase is large, old, or has no documentation.
- You must make a change that crosses module boundaries (new feature,
refactor, migration, or a bug whose cause is unknown).
- You are reviewing or extending code written by someone else.
- You need to give another agent or teammate a fast, accurate orientation.
Do NOT use it when:
- The change is a one-liner in a self-contained script — the "map" is the
file itself.
- You already hold the map, commands, and conventions in working notes from
a recent pass (recon fresh, not ritual).
The Recon Pass
Five steps, in order. Each step ends with a concrete output to record.
Step 1 — Read the map
Grok the shape of the repo before reading any implementation.
- Read
README, ARCHITECTURE, docs/, and any ADRs first.
- List the top-level directory tree; identify entry points (
main,
index, server, CLI entry, worker, App component).
- Skim the manifest:
package.json, pyproject.toml, go.mod,
Cargo.toml, composer.json, Gemfile, pom.xml, etc. — it names the
real dependencies and scripts.
- Note what the repo is NOT (no tests? no docs? monorepo? library vs app?).
Output: a one-paragraph mental model: "This is a FastAPI service that
ingests webhooks, transforms them into events, and writes them to
Postgres. Entry point is app/main.py; it has no test suite."
Step 2 — Learn the commands
Find the exact commands before running anything guessed.
- Check
README/CONTRIBUTING, Makefile, Justfile, Taskfile, and
the package-manifest scripts block.
- Identify: install, build, test, lint, and run/dev commands.
- Verify at least one command end-to-end (usually the test suite, or build
if tests are slow). A command that "should work" is not a command that
works.
Output: a cheat-sheet of verified commands with their working directory:
npm install && npm test # from repo root
uv run pytest tests/ -x # fast subset for iteration
Step 3 — Trace one flow end-to-end
Pick ONE representative flow (a user-facing feature, a request lifecycle, a
job) and follow it from entry point to output, database, or side effect.
- Jump from call site to definition with search; read the actual code.
- Note file:line anchors for each hop.
- One flow is enough for reconnaissance — do not trace three.
Output: a written trace, e.g.:
POST /orders -> app/routes/orders.py:12 -> OrderService.create() (services/orders.py:41)
-> validates via schemas/order.py -> writes Order (models/order.py:88)
-> enqueues email job (jobs/email.py:30)
Step 4 — Note conventions, then match them
Identity the local style and follow it, even when you would write it
differently. Your taste is not the repo's law.
- Naming:
snake_case? camelCase? prefixes? file-per-class?
- Structure: where do errors get handled? Where do types/schemas live?
- Testing style: unit vs integration, framework, test-file placement.
- Error handling and logging patterns; commit/PR style if visible.
Output: a short convention list you will consciously match on every edit.
Step 5 — Write it down
Commit the recon to durable notes, not memory.
- Write
RECON.md at the repo root (or .gitignore it) for team/other-agent
reuse, or keep a session note if the repo is private and throwaway.
- Include: the map paragraph, verified commands, the flow trace, the
convention list, and any open questions.
- If your recon uncovered a TODO or landmine, record it here — do not fix it
yet (see Cross-reference).
Output: the file you (or the next agent) will read to skip this pass next
time.
Standing Rules
- Search before assuming. Never assume a helper, pattern, or file
exists — grep for it first. The cost of one
rg is trivial; the cost of
a wrong assumption is a broken build.
- Verify before believing. Reading the README is not understanding the
code. Confirm claims against the actual sources and a real command run.
- Do not change code during recon. No drive-by fixes, no refactors, no
"quick improvements." During the pass, code is read-only; your only
artifact is the recon note.
- Match, don't impose. When local convention conflicts with your
preference, the convention wins.
- Read the file you are about to modify — fully, not just the hunks
around your edit.
- Ask when the map contradicts reality. If docs say X and code does Y,
trust code, flag the drift, and ask if the intended behavior is X or Y.
Definition of Done
The recon pass is complete when you can answer all five questions from the
overview, and the answers are written down:
Common Mistakes
- Skipping the map and diving into a random file. You will misread
intent and misfile changes. Read the map first, always.
- Guessing commands instead of reading the manifest or Makefile. A
guessed command that half-works wastes more time than reading it.
- Tracing too many flows. One traced flow beats three half-traced ones;
reconnaissance is breadth-first by design.
- "Fixing" things you find during recon. Resisting the drive-by fix is
the whole point — record, defer, and let the fix clear its own review.
- Trusting stale memory of a similar repo. Same framework does not mean
same conventions. Every repo gets its own pass.
- Keeping the recon in your head. Unwritten recon evaporates with the
session; the note is what makes the next session (yours or another
agent's) fast.
Cross-reference
- anti-over-engineering — pair with this skill. Recon exists to
understand, not to add or remove abstraction. When the pass surfaces
over-built code, record it in the recon note and defer any simplification
to a scoped cleanup, evaluated against the anti-over-engineering skill's
criteria. A cleanup that starts during recon is an over-engineering
failure in disguise.
- understand / codebase-inspection — deeper long-form codebase analysis
for large migrations or onboarding docs; repo-recon is the fast,
change-oriented variant.
1---2name: repo-recon3description: >4 Use this skill when you need to map an unfamiliar codebase before changing5 anything. Runs a systematic five-step recon pass — read the map, learn the6 commands, trace one flow end-to-end, note conventions then match them, and7 write it down — so you understand architecture, build/test commands, and8 code conventions before making a single edit. Prevents broken builds,9 misfiled changes, and convention-violating PRs caused by search-before-assuming.10 Activates on "where do I start", "understand this codebase",11 "how do I build/test this", "what are the conventions here", and first-time12 work in any repository.13version: 1.0.014author: JPeetz15license: MIT16compatibility: >17 Cross-platform: Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Windsurf,18 Gemini CLI, OpenClaw, Hermes Agent, and any SKILL.md-compatible agent.19tags:20 - codebase-navigation21 - code-reading22 - onboarding23 - repository-analysis24 - code-quality25 - conventions26platforms:27 - claude-code28 - codex29 - cursor30 - gemini-cli31 - openclaw32 - copilot33 - windsurf34metadata:35 source: https://skillmd.com/skills/jpeetz/repo-recon36---3738# Repo Recon3940Systematically map an unfamiliar codebase before changing anything. The recon41pass is a short, bounded sequence — minutes, not hours — that front-loads the42understanding you would otherwise pay for painfully later in broken builds,43rejected PRs, and rewrites. It is the "before" half of every safe edit.4445## Overview4647Reconnaissance is cheap; guessing is expensive. Before you touch a single48line, spend a few minutes answering five questions:49501. What is this repo and how is it laid out?512. How do I build, test, and run it?523. Where does one real flow live, and how does it work end-to-end?534. What conventions must my code match?545. Where did I write all of this down?5556The five-step pass below answers them in order. The output is a written57recon note: a map, a command cheat-sheet, one traced flow, and a convention58list. That note is the deliverable — not code changes.5960## When to Use6162Use this skill when:6364- You are working in a repository for the first time.65- You are returning to a repo after a long absence (memory is stale).66- The codebase is large, old, or has no documentation.67- You must make a change that crosses module boundaries (new feature,68 refactor, migration, or a bug whose cause is unknown).69- You are reviewing or extending code written by someone else.70- You need to give another agent or teammate a fast, accurate orientation.7172Do NOT use it when:7374- The change is a one-liner in a self-contained script — the "map" is the75 file itself.76- You already hold the map, commands, and conventions in working notes from77 a recent pass (recon fresh, not ritual).7879## The Recon Pass8081Five steps, in order. Each step ends with a concrete output to record.8283### Step 1 — Read the map8485Grok the shape of the repo before reading any implementation.8687- Read `README`, `ARCHITECTURE`, `docs/`, and any ADRs first.88- List the top-level directory tree; identify entry points (`main`,89 `index`, `server`, CLI entry, worker, `App` component).90- Skim the manifest: `package.json`, `pyproject.toml`, `go.mod`,91 `Cargo.toml`, `composer.json`, `Gemfile`, `pom.xml`, etc. — it names the92 real dependencies and scripts.93- Note what the repo is NOT (no tests? no docs? monorepo? library vs app?).9495**Output:** a one-paragraph mental model: *"This is a FastAPI service that96ingests webhooks, transforms them into events, and writes them to97Postgres. Entry point is `app/main.py`; it has no test suite."*9899### Step 2 — Learn the commands100101Find the exact commands before running anything guessed.102103- Check `README`/`CONTRIBUTING`, `Makefile`, `Justfile`, `Taskfile`, and104 the package-manifest `scripts` block.105- Identify: install, build, test, lint, and run/dev commands.106- Verify at least one command end-to-end (usually the test suite, or build107 if tests are slow). A command that "should work" is not a command that108 works.109110**Output:** a cheat-sheet of verified commands with their working directory:111112```113npm install && npm test # from repo root114uv run pytest tests/ -x # fast subset for iteration115```116117### Step 3 — Trace one flow end-to-end118119Pick ONE representative flow (a user-facing feature, a request lifecycle, a120job) and follow it from entry point to output, database, or side effect.121122- Jump from call site to definition with search; read the actual code.123- Note file:line anchors for each hop.124- One flow is enough for reconnaissance — do not trace three.125126**Output:** a written trace, e.g.:127128```129POST /orders -> app/routes/orders.py:12 -> OrderService.create() (services/orders.py:41)130 -> validates via schemas/order.py -> writes Order (models/order.py:88)131 -> enqueues email job (jobs/email.py:30)132```133134### Step 4 — Note conventions, then match them135136Identity the local style and follow it, even when you would write it137differently. Your taste is not the repo's law.138139- Naming: `snake_case`? `camelCase`? prefixes? file-per-class?140- Structure: where do errors get handled? Where do types/schemas live?141- Testing style: unit vs integration, framework, test-file placement.142- Error handling and logging patterns; commit/PR style if visible.143144**Output:** a short convention list you will consciously match on every edit.145146### Step 5 — Write it down147148Commit the recon to durable notes, not memory.149150- Write `RECON.md` at the repo root (or `.gitignore` it) for team/other-agent151 reuse, or keep a session note if the repo is private and throwaway.152- Include: the map paragraph, verified commands, the flow trace, the153 convention list, and any open questions.154- If your recon uncovered a TODO or landmine, record it here — do not fix it155 yet (see Cross-reference).156157**Output:** the file you (or the next agent) will read to skip this pass next158time.159160## Standing Rules1611621. **Search before assuming.** Never assume a helper, pattern, or file163 exists — grep for it first. The cost of one `rg` is trivial; the cost of164 a wrong assumption is a broken build.1652. **Verify before believing.** Reading the README is not understanding the166 code. Confirm claims against the actual sources and a real command run.1673. **Do not change code during recon.** No drive-by fixes, no refactors, no168 "quick improvements." During the pass, code is read-only; your only169 artifact is the recon note.1704. **Match, don't impose.** When local convention conflicts with your171 preference, the convention wins.1725. **Read the file you are about to modify** — fully, not just the hunks173 around your edit.1746. **Ask when the map contradicts reality.** If docs say X and code does Y,175 trust code, flag the drift, and ask if the intended behavior is X or Y.176177## Definition of Done178179The recon pass is complete when you can answer all five questions from the180overview, and the answers are written down:181182- [ ] One-paragraph map: what the repo does and its top-level structure.183- [ ] Verified install/build/test/run commands.184- [ ] One flow traced end-to-end with file:line anchors.185- [ ] Convention list that your edits will match.186- [ ] Recon note written to disk (or session notes for throwaway repos).187- [ ] Zero source changes made during the pass.188189## Common Mistakes190191- **Skipping the map and diving into a random file.** You will misread192 intent and misfile changes. Read the map first, always.193- **Guessing commands instead of reading the manifest or Makefile.** A194 guessed command that half-works wastes more time than reading it.195- **Tracing too many flows.** One traced flow beats three half-traced ones;196 reconnaissance is breadth-first by design.197- **"Fixing" things you find during recon.** Resisting the drive-by fix is198 the whole point — record, defer, and let the fix clear its own review.199- **Trusting stale memory of a similar repo.** Same framework does not mean200 same conventions. Every repo gets its own pass.201- **Keeping the recon in your head.** Unwritten recon evaporates with the202 session; the note is what makes the next session (yours or another203 agent's) fast.204205## Cross-reference206207- **anti-over-engineering** — pair with this skill. Recon exists to208 understand, not to add or remove abstraction. When the pass surfaces209 over-built code, record it in the recon note and defer any simplification210 to a scoped cleanup, evaluated against the anti-over-engineering skill's211 criteria. A cleanup that starts during recon is an over-engineering212 failure in disguise.213- **understand / codebase-inspection** — deeper long-form codebase analysis214 for large migrations or onboarding docs; repo-recon is the fast,215 change-oriented variant.