map-codebase

Map Codebase

Overview

A methodical exploration workflow that produces an evidence-cited map of a codebase area. Replaces ad-hoc grep with a disciplined four-step pass: scope, list, read, diagram. The output is a short artifact you can attach to a plan or design doc — file paths, line numbers, call directions, and the questions you couldn't answer from reading. The skill's value is enforcing that every claim about the code is backed by a specific file:line citation, not a memory or pattern-match. Senior ICs and tech leads use it to bound the blast radius of a change before they propose it.

When to Use

• Before writing a plan that touches more than one module
• When inheriting a codebase area you didn't author
• When a teammate asks "how does X work" and you don't have a confident answer with citations
• Before a refactor, to enumerate everything that calls the code you're about to change
• When debugging crosses a boundary you don't fully understand (auth, ORM, framework internals)

When NOT to Use

• The change is single-file and you've already read the file
• You're modifying code you wrote yourself within the last week
• The "exploration" is really a one-line lookup that Grep answers in 5 seconds

Process

Step 1: Scope

Goal: Pin down what you are mapping and what you explicitly are not.

Inputs: A task, plan, or question that triggered the need to explore.

Actions:

1. Write one sentence: I am mapping <X> in order to <Y>. X is concrete (a feature, a module, a request path). Y is the decision the map will support.
2. Write one sentence naming what is out of scope: I am not mapping <Z>. This prevents the exploration from sprawling.
3. Set a time box. 30 minutes for a single feature, 90 minutes for a subsystem.

Output: A two-sentence scope statement at the top of your scratch artifact.

Step 2: List entry points

Goal: Enumerate every place execution can enter the area being mapped.

Inputs: The scope statement.