Before we start ripping, I want to make a skill out of mapping the repository. The targeted map we built a few episodes back was the most useful thing to come out of the exploration phase, and I do not want to reinvent it on the next repo.

I am a few sessions ahead of where you last saw me, so the trick here is /resume. Claude Code keeps every session I have been part of: audit and prune, review Copilot artifacts, plan a Git strategy, and there it is, the Copilot mapping session. I pick it up, tell it to summarize all the work we did to create the map, and ask for a skill called repo recon saved locally in this project's .claude directory.

A note on models, because it has been a few weeks since I recorded and things moved. I have been running Opus 5 for most of this project and I love it. Fable 5.1 just dropped and it is very good, but it is expensive, and I save it for things that need real thinking. Summarizing a session into a skill is not one of those. Opus it is.

The skill comes back in a minute. First pass is too specific: "short targeted map of one subsystem built from docs/copilot-map.md." That is tied to this project, so I send it back and ask it to genericize the thing. I want to reuse this on any repo. I am keeping it local for now, though, because I suspect it will evolve as the real work starts.

What I like about how it landed: it is a targeted recon skill, not a whole-repo mapper. That is the right shape. If you need a map of everything, there are better tools. Graphify is fun. Repomix made us a 200MB file we could not use, but it exists. The recon skill is for the question I actually keep asking, which is "show me this one subsystem and nothing else."

Second pass is generic. Repo recon is in the kit.

The Skill

---
name: repo-recon
description: Build a small, targeted, independently-verified map of one subsystem in any repo (e.g. "everything auth-related", "everything payments-related") and write it to a docs/ folder. Use when asked to map, scope, or survey a slice of a codebase before a removal or refactor — not for full codebase exploration. Never use the Explore agent or broad fan-out search agents for this; do the recon directly.
---
repo-recon
Produces a short, targeted map of one subsystem within a codebase — not a
full codebase map. Works on any repo, any language, any size.
When to use
The user wants to know "where does X live" across a repo, scoped to one theme
(a feature to remove, a subsystem to refactor, a vendor integration to rip
out, a cross-cutting concern to audit) — and wants the answer as a durable
doc, not a one-off chat answer.
Don't use this for open-ended "explore the codebase" requests, and don't use
it if a map for the same theme already exists in the repo's docs location —
read and extend that instead of re-deriving it, unless the user explicitly
asks to ignore existing docs and redo the recon independently.
Method
Everything in the output must be something you personally observed this
session — ls, grep, find, Read — not recalled from training data, not
copied from another doc without checking it's still true. If an existing map
or skill claims a path, verify it still exists before citing it; note drift
if it doesn't.

Scope the theme. Get a precise keyword/concept set from the user (e.g.
"everything auth-related" or "Stripe and anything billing-related"). Ask
before including adjacent-but-fuzzy territory (e.g. "does session-cookie
handling count, or only the third-party auth provider code?") rather than
guessing.

Find candidate directories first, file-level grep second. Start broad
and cheap:
ls <top-level dirs>
ls <dir> | grep -iE "<keyword1>|<keyword2>|..."
grep -ril "<keyword>" --include="*.json" . | grep -v node_modules
Only grep file contents inside candidates you've already located by name —
don't full-text search the whole tree first.

Get file counts per candidate, largest first — this is what tells the
reader where the real mass is:
for d in <candidates>; do echo "$(find "$d" -type f | wc -l)  $d"; done | sort -rn

Find the entry points — the small number of files that wire everything
else in. In an import-graph codebase this is usually one or two "main"
files; grep them for the theme's keywords to get exact import lines, not
just directory names. This is the highest-leverage part of the map: it's
the first thing to touch and the cheapest way to disable a feature before
deleting anything.

Find config/build wiring — feature flags, product/package manifests,
build-system directory lists — anything that references a candidate path
by string outside the source tree itself.

Flag genuinely uncertain boundaries as an explicit open question rather
than silently including or excluding them (e.g. a renderer shared between
the target theme and unrelated features). Don't delete-by-implication in
the map — call out what needs a human judgment call.

Write the map to a doc. Find where this repo keeps its own working
docs (a docs/, .claude/, or similar directory the project already
uses) and put it there as <theme>-map.md; if nothing like that exists,
ask the user where they want it. Structure:

One-line scope statement + keep-list (what's explicitly out of scope)
Biggest targets by file count, in a table, with a one-line description each
Everything else, same table format, smallest detail last
Entry-point section with literal import lines / config keys, so the next
session can act without re-deriving them
Build/config wiring section
Suggested order of operations if this map feeds a removal (entry points
first, then folders largest-to-smallest, then config cleanup, then fix
compile fallout)
Open questions section for anything ambiguous



Keep the whole doc scannable in under two minutes — this is a lookup table,
not a report. Bullet/table over prose wherever possible.
Verification discipline

Prefer ls + grep -c/find | wc -l over trusting a comment or README
that describes what a folder "used to be" — code drifts, comments don't
get updated.
If a pre-existing artifact (another map, a skill, a doc) disagrees with
what's on disk, disk wins — say so in the output rather than silently
reconciling.
Don't launch Explore or general-purpose search agents for this — they read
excerpts and can miss content past their read window, which is exactly
wrong for a map that's supposed to be a source of truth. Do the ls/grep
yourself so every line in the map is something you actually saw.