SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsrepo-recon

repo-recon

Coding & development

View repository

Updated 11-13 16:16

About this skill

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:

  1. What is this repo and how is it laid out?
  2. How do I build, test, and run it?
  3. Where does one real flow live, and how does it work end-to-end?
  4. What conventions must my code match?
  5. 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

  1. 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.
  2. Verify before believing. Reading the README is not understanding the code. Confirm claims against the actual sources and a real command run.
  3. 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.
  4. Match, don't impose. When local convention conflicts with your preference, the convention wins.
  5. Read the file you are about to modify — fully, not just the hunks around your edit.
  6. 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:

  • One-paragraph map: what the repo does and its top-level structure.
  • Verified install/build/test/run commands.
  • One flow traced end-to-end with file:line anchors.
  • Convention list that your edits will match.
  • Recon note written to disk (or session notes for throwaway repos).
  • Zero source changes made during the pass.

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.