Map ownership in an unfamiliar repository

2141. Lesson identity

Module

5.6 — Large codebase strategy

Lesson

Map ownership in an unfamiliar repository

Academic type

Systems

Schema type

text

Order

1

Estimated time

35–45 minutes, including practice

2142. Learning objective

After this lesson, you can produce a repository map that identifies the relevant systems, entry points, data owners, dependency boundaries, one safe change location, and the main risks of changing it.

2143. Why this matters

An unfamiliar repository does not present its architecture in the order you need it. A plausible file can still be the wrong place to make a change because another system owns the state, another layer controls the lifecycle, or several consumers depend on the same interface. Mapping ownership turns repository exploration into a constrained engineering decision. It also gives you a precise brief to evaluate before asking an AI tool to suggest or implement a change.

2144. Prior knowledge

You should be able to inspect a proposed change, review the actual diff, validate the result, and recover when the result is unsafe. This lesson builds directly on 5.5 L2 — Inspect, validate, and recover. You should also be familiar with the project’s basic language, directory structure, and normal validation commands.

2145. Core concept

The central idea is ownership before modification.

For any requested change, distinguish four things:

1. System: Which subsystem performs the behavior?
2. Entry point: Where does the behavior begin or where does the relevant request enter the system?
3. Data owner: Which component creates, stores, or authoritatively changes the state?
4. Boundary: Which interfaces, events, services, scenes, modules, or consumers must remain compatible?

A file that displays a value may not own it. A function that receives an event may not define the rule behind it. A central utility may be easy to edit but risky because many unrelated systems depend on the same interface. The safe change location is the narrowest authoritative location that satisfies the request without crossing an unnecessary boundary.

2146. Mental model

Use the S-E-D-B map:

Then add a decision line:

Requested behavior → S-E-D-B evidence → safest change location → likely risks → validation evidence

Do not treat the map as a complete architecture diagram. It is a decision map for one change. Its value comes from recording evidence and uncertainty, not from drawing every dependency in the repository.

2147. Concrete example

Suppose the request is: “When a completed task grants a reward, prevent the reward from being granted twice.”

A weak orientation might select the screen that displays the reward and add a guard there. That screen is an observer, not necessarily the owner.

A stronger S-E-D-B map might look like this:

The safer candidate is the authoritative reward-resolution path, provided the evidence confirms that all completion sources use it. The display layer remains a risk surface because changing it may hide duplicate rewards without preventing them. Additional risks include retries, loaded completed tasks, and callers that bypass the suspected entry point.

The example demonstrates the decision, not a project-specific implementation. You must verify each finding in the repository before changing code.

2148. Common mistake

The most common mistake is equating visibility with ownership. Developers often choose the file where a value is shown, logged, or initially received because it is easy to find. This can create duplicated rules, leave alternate entry points unprotected, or introduce a fix that works only for one caller.

Another mistake is drawing a dependency map from filenames alone. Names are clues. Imports, call sites, state mutations, event flows, tests, and runtime configuration provide stronger evidence.

2149. Guided practice and practical assessment

Use the bounded unfamiliar repository snapshot below. The request is: “A completed task should not apply its reward more than once.” Do not propose or write an implementation.

Repository snapshot

src/tasks/TaskCompletionService.ts
src/rewards/RewardLedger.ts
src/ui/RewardToast.ts
src/save/SaveCodec.ts
config/event-bindings.json
tests/TaskCompletionService.test.ts
tests/RewardLedger.test.ts

The supplied evidence contains these excerpts:

• config/event-bindings.json: task_finished is routed to TaskCompletionService.complete.
• src/tasks/TaskCompletionService.ts, symbol complete: marks the task complete, calls RewardLedger.grantForTask, and then publishes task.completed.
• src/rewards/RewardLedger.ts, symbols grantForTask and restore: grantForTask appends a reward entry and updates the balance; restore replaces ledger entries from saved data.
• src/ui/RewardToast.ts, symbol onTaskCompleted: subscribes to task.completed and reads the current balance; it does not mutate task or reward state.
• src/save/SaveCodec.ts, symbols encode and decode: serialize and restore both task state and reward-ledger entries.
• Symbol references show that production code calls grantForTask only from TaskCompletionService.complete; mutation of reward-ledger entries occurs only inside RewardLedger.
• tests/TaskCompletionService.test.ts covers one normal completion. tests/RewardLedger.test.ts covers one grant and one restore, but neither test covers repeated completion or grant replay.
• Relevant history note: a prior change moved reward-entry mutation from TaskCompletionService into RewardLedger to centralize reward writes. The note does not address duplicate prevention.

Required AI verification workflow

1. Give an AI tool only the request, file list, and selected excerpts. Ask it to propose candidate search paths or summarize the responsibilities of the selected files.
2. Record each useful AI statement in a claim log with four fields: claim, proposed source, verification result, and citation.
3. Verify or reject every claim against the supplied source excerpts, symbol references, tests, configuration, or history note. Cite file paths and symbols, such as src/rewards/RewardLedger.ts::grantForTask; the AI summary itself is not evidence.
4. Mark unsupported claims unknown rather than filling gaps with guesses.

Submission

Submit one text artifact named repository-map.md containing:

1. an S-E-D-B map with evidence paths and confirmed, inferred, or unknown labels;
2. the AI claim log;
3. one accepted future change location and one rejected location, each justified with repository evidence;
4. at least three risks, with one risk-linked validation check for each; and
5. the evidence that would make you revise the accepted location.

The mandatory decision is: Which location would you authorize for a future change, and what evidence would make you change that decision?

2150. Validation / evidence

A reviewer scores repository-map.md out of 20 points:

A passing submission earns at least 15/20 and scores at least 2 points in every criterion. The multiple-choice quiz remains a secondary knowledge check; it does not replace this practical assessment.

2151. Key takeaways

• Map ownership before selecting a file to change.
• Separate the system, entry point, data owner, and boundary.
• Prefer repository evidence over filenames or AI-generated guesses.
• Choose the narrowest authoritative change location, not merely the easiest file to edit.
• Record uncertainty and risks so later inspection can test the decision.

2152. Next lesson

Continue to 5.6 L2 — Plan a staged multi-system change. Carry the approved change location, ownership boundaries, risks, unresolved uncertainties, and validation checks from your repository map into that lesson as constraints for the staged plan.

2153. Knowledge check