Mapping the Codebase

Before you touch unfamiliar code, map who calls it, what it owns, and where its boundaries are.

When to use

• You're about to plan, change, debug, or extend a part of the codebase you don't know well.
• Skip only when a Step 3 boundary record for this region exists and is inside its freshness limit.

Step 1: Set the boundary

1. Before reading anything, write the intended change, how far it could reach, and why the boundary you picked holds that reach. For a compatibility-sensitive change, never stop at direct callers.
2. Pin the repository or working state and the identity of every external input the reading depends on. Write what makes the reading stale.

Step 2: Map

1. Start at the containing module and its neighbors: responsibilities, runtime entry points, callers, collaborators, data between them.
2. As risk warrants, trace: generated code and build inputs; persistent state and migrations; public contracts and consumers; configuration, deployment, operational paths; the toolchain and the commands that build, run, and check it; tests, CI, proof surfaces; ownership and change history. Give an evidence-based reason for each surface on that list you leave out.
3. Use the domain's vocabulary, never "service / handler / util".
4. Attach each conclusion to current files, symbols, searches, commands, or revisions. Separate what you observed from what you inferred. Mark what is stale or unavailable.

Step 3: State the boundaries

1. Write the boundary record to .sdlc-skills/evidence/{{YYYY-MM-DD}}-{{topic}}/boundary-record.md unless the user names another path: what the region owns, what it delegates, where its seams are, which downstream obligations a change must preserve.
2. Set a freshness limit. Once it has passed, or a pinned input has changed, revalidate the affected claims before relying on them.
3. If implementation finds a caller or surface the map never covered, stop editing and return to Step 1 with it: recheck that the boundary holds the change's reach, map the surface from the code, and update the record before the next edit. Never extend the map from memory.

Gotchas

• A caller reached through configuration, reflection, a generated route, or a scheduler never appears in an import search, so a map built from imports draws a boundary that a runtime caller crosses.
• A boundary record carries no signal of its own staleness; past its freshness limit it reads exactly like a current one.