Read an unfamiliar code repository quickly and defensibly

Fast repository reading is about reaching a bounded claim sooner, not guessing sooner

You are handed a checkout of a service you have never seen. The change request sounds small: locate the coupon path and identify what would need inspection before a later change. A directory called src/api looks convincing. Search returns several coupon matches there. Yet the runtime registration and the tests that are actually discovered live elsewhere.

If you now say “I understand the architecture” or “this is the active implementation,” your conclusion is stronger than your evidence.

The deliverable for this lesson is a Repository Reconnaissance Record v1, not a mental feeling of familiarity. The record must make it possible for another engineer to inspect:

• the repository/workspace boundary you used;
• the questions that led to concrete anchors;
• which statements are observed, bounded inferences, or still unknown;
• which tempting cues you rejected and why;
• and the point at which you chose to stop, take one more discriminating step, or defer.

Approximate active time: 65 minutes.

Use this lesson when: you need a fast, reviewable map of an unfamiliar repository before editing or debugging, including boundary, manifests, runtime/wiring anchors, test discovery, and a bounded feature trace.

Do not use it as: root-cause diagnosis, proof of implementation correctness, proof of every runtime path, or a complete Test Strategy.

Hard prerequisite: you can keep request, context, evidence, and unverified AI/tool output separate.

Prerequisite probe

An AI assistant says: “I found src/api/coupon.py, therefore it is the entry point.” In three short statements identify:

1. what was actually observed;
2. what is still inference;
3. what additional evidence would be needed for a stronger claim.

PASS: your conclusion stays inside the available evidence and final judgment is not delegated to the assistant.

If that distinction is fragile, repair only this dependency: treat an AI/tool result as candidate evidence until you can name a locator, a claim boundary, and a human decision. The previous lesson is not re-taught here.

Choose your support level without changing the evidence standard

The foundation, repair, and experienced routes end at the same artifact, lab, transfer task, and review threshold.

Route probe

Answer each question briefly:

1. Why is a directory name a cue rather than proof?
2. When does a search hit become useful reconnaissance evidence?
3. What distinguishes OBSERVED from INFERRED?
4. Why is finding a test file different from finding test-discovery evidence?
5. What condition tells you to stop or defer?

5/5 → Fast Path; 3–4/5 → targeted repair; 0–2/5 → foundation route.

Foundation gives you explicit vocabulary and a worked trace. Repair adds one contrast on the weak dimension. Experienced learners may skip explanation, but not the artifact or transfer evidence.

Mental model: reconnaissance is a sequence of discriminating questions

Do not model the task as “browse until the repository feels familiar.” Use this loop instead:

Question → Anchor → Evidence type → Bounded claim → Next discriminating question → Stop/Defer

Keep three layers distinct:

1. Repository shape: files, directories, manifests, and configuration that exist.
2. Runtime reachability evidence: registration, imports, entry points, or wiring that make one path more plausible as active.
3. Causal behavior: what executes in a real run and why a defect occurs.

This lesson connects the first layer to bounded evidence from the second. It does not claim the third.

A useful search is not the one with the most hits. It is the one that changes the candidate set or closes a specific evidence gap. Record confidence as categories such as OBSERVED, INFERRED, and UNKNOWN; do not manufacture numeric confidence scores that the evidence cannot support.

Foundation concepts

Repository/workspace boundary

Before interpreting internal structure, state which checkout or workspace the record is about. Git root, top-level manifests, workspace configuration, and a tracked-file inventory can provide boundary anchors.

Anchor

An anchor is an inspectable locator relevant to the current question: a manifest, runtime registration, entry point, test-discovery configuration, import/wiring location, or a test connected to the wired path. The anchor must be paired with the claim it actually supports.

Search trace

A trace records question → query/action → result → discriminating value → next question. A pile of search hits is not a trace if no one can tell which result changed the map.

Observed, inferred, unknown

OBSERVED is directly locatable in the repository or command output. INFERRED combines observations into a bounded conclusion that still lacks direct proof. UNKNOWN means the current evidence does not justify a conclusion.

Stop/defer boundary

Reconnaissance is finite. Stop when the bounded question has enough reviewable evidence. Defer when the desired claim requires dynamic execution, debugging, broader test strategy, or another authority.

Two Git instruments used here

git ls-files can be used to enumerate file information from the index and working tree according to selected options. That command does not decide repository architecture.

git grep can be used for bounded pattern search in tracked/worktree content. A text match is an anchor candidate, not proof that code executes.

Short exercise: separate observation from active execution

Scenario: src/api/coupon.py appears in the tracked-file inventory and a text search also hits it. Can you conclude that it is the active runtime entry?

Your response must do two things:

1. bound the claim as OBSERVED / INFERRED / UNKNOWN;
2. name the missing evidence required for a stronger claim.

A six-step reconnaissance method

1. Bound the change question

Replace “How does this repository work?” with a question that has an exit condition, such as: “For feature X, which anchors identify the wired implementation and relevant test-discovery path?”

2. Establish boundary and manifests

Find the repository/workspace boundary, then inspect top-level manifests and configuration. Use directory names to form questions, not architecture conclusions.

3. Find a wiring or runtime anchor

Start from language present in the change brief: feature key, command name, route label, event, or identifier. Record every search as a trace. When multiple plausible implementations exist, look for registration/import/wiring evidence that discriminates among them.

4. Establish test discovery separately

A file named test_.py, .spec.*, or a directory called tests does not by itself prove discovery. Locate the runner/configuration anchor that defines the discovered surface, then connect a relevant test to the feature trace.

5. Label claims and rejected cues

Every blocking conclusion needs an evidence locator, a status (OBSERVED / INFERRED / UNKNOWN), and a statement of what the evidence does not prove. Keep rejected cues in the record so a reviewer can inspect why the obvious path was not promoted.

6. Make a human stop decision

Choose one of three states:

• STOP_WITH_BOUNDED_MAP — the bounded question is reviewable;
• CONTINUE_ONE_DISCRIMINATING_STEP — one defined evidence gap remains;
• DEFER_ESCALATE — the desired claim requires a different investigation mode.

AI and documentation may support exploration only after you have closed a retrieval/first-diagnosis probe without relying on that support. Disclose the support, independently validate locators and evidence, and keep the final evidence-sufficiency decision human-owned.

Worked case: tracing a coupon feature without trusting the obvious folder

A synthetic service contains these plausible locations:

• config/service.yaml
• bootstrap/plugins.py
• domain/promotions/coupons.py
• quality/scenarios/test_coupon_flow.py
• src/api/coupon_handler.py

The last path looks exactly like what a quick browser might choose first. Treat that appearance as a hypothesis.

Trace A — boundary. A tracked-file inventory and top-level configuration establish the checkout boundary and reveal multiple coupon candidates. The existence of those files is observed; active runtime status remains unknown.

Trace B — wiring. A bounded search for the feature identifier reaches bootstrap/plugins.py, where the implementation in domain/promotions/coupons.py is registered. The src/api candidate has no corresponding registration evidence. The registration strengthens a runtime-reachability claim, but it is still not proof of every runtime path.

Trace C — tests. Runner configuration identifies quality/scenarios/ as a discovery root. A coupon test there reaches the feature through the registered path. This establishes a test anchor; it does not prove production correctness.

Rejected cue. src/api/coupon_handler.py stays in the record as a plausible but unsupported route rather than being silently discarded.

The original reconnaissance question is now closed, so the defensible outcome is STOP_WITH_BOUNDED_MAP. Root cause and correctness remain explicit non-claims.

Short exercise: challenge a plausible shortcut

An architecture note says the coupon handler is under src/api/, and that path also exists in the repository. The shortcut is to declare it the active implementation.

Submit three lines:

1. why that shortcut crosses the claim boundary;
2. which current evidence is only a cue;
3. one genuinely discriminating next step such as a registration/import/wiring lookup.

Common failure modes

The obvious folder becomes “the architecture”

Folder naming is convention evidence, not execution evidence. Repair by finding an independent manifest, registration, or import anchor before promoting the claim.

Search volume becomes confidence

Twenty matches are not twenty confirmations. Repair by recording what each query discriminated. Discard hits that do not alter the bounded map.

A test filename is treated as discovery proof

Repair by locating the test runner or configuration that determines the discovered surface.

A static map becomes behavioral proof

If the conclusion changes from “this path is wired” to “this behavior is correct” or “this caused the defect,” stop. The question has crossed into debugging or test strategy.

Browsing has no exit condition

Repair by restating the bounded question and allowing only the next highest-value discriminating step.

AI summary becomes source authority

Repair by turning the summary into search options or hypotheses. Record the underlying repository/source locators and keep final judgment with the learner/reviewer.

Experienced bridge: keep your fast tools, expose their evidence

Experienced engineers may jump through IDE navigation, language-server references, rg, dependency views, or AI repository summaries. That speed is useful if the resulting reasoning can still be audited.

For every fast jump, capture four things: the question, the returned anchor, the bounded claim it supports, and the alternative or unknown that remains. If an IDE takes you directly to a definition, you still need independent wiring/test-discovery evidence before calling it active. AI/documentation support is allowed only after a retrieval/first-diagnosis probe has been closed independently; after that, inspect every supplied locator before accepting any claim.

Fast Path removes scaffolding. It does not remove the record or the changed-context transfer requirement.

Alternatives and trade-offs

Choose the lowest-cost evidence that actually discriminates between important candidates. Once the question becomes causal, do not disguise debugging as “more reconnaissance.”

Guided practice and independent lab

First, reconstruct the opening rows of the worked coupon record without copying its prose. Include a bounded question, one boundary/manifest anchor, one search action, one claim label, one rejected cue, and a stop condition.

Then move to the supplied local lab repository. The learner can see the complete checkout and the change brief, but not the canonical anchor map.

Your lab record must:

1. identify the repository/workspace boundary and at least one manifest anchor;
2. identify runtime registration and test-discovery anchors;
3. trace the requested feature to a wired implementation and a relevant test;
4. classify at least one tempting cue as rejected or uncertain;
5. expose unknowns and non-claims;
6. end with a human stop/defer decision without claiming root cause or correctness.

Independent execution

Fast Path learners go directly to the lab with the blank record. Foundation learners may use the structured template for the first pass, but prompts are removed before the transfer task.

AI/documentation support is allowed only after a retrieval/first-diagnosis probe has been closed independently. Any such support must be disclosed, and the final evidence trail and claim boundaries must be defensible without trusting it as an oracle.

Short exercise: review your record independently

Before summative transfer, inspect your record without the worked example open. It must contain all three:

• evidence locators and status labels for central claims;
• a human stop/defer decision with rationale;
• an explicit limitation/non-claim, with no unsupported inference promoted to fact.

What makes the reconnaissance record reviewable?

A reviewer inspects five critical dimensions:

1. Boundary correctness — the record clearly identifies the repository/workspace under discussion.
2. Traceability of anchors — blocking conclusions can be traced to locators and search actions.
3. Fact/inference/unknown separation — no inference is silently promoted to fact.
4. Resistance to misleading cues — at least one plausible cue has an explicit disposition.
5. Transfer — the method creates new evidence in a changed layout rather than copying example paths.

The minimum evidence package is the completed record, lab trace, at least one explicit limitation/non-claim, support disclosure, and a human review decision. ACCEPT means the record is defensible for its bounded question. It does not certify the entire architecture or runtime behavior.

A failed critical dimension cannot be compensated for by averaging strong scores elsewhere.

Assessment and changed-context transfer

The assessment covers five evidence types:

• S1 retrieval: distinguish boundary/anchor and fact/inference/unknown in a compact scenario.
• S2 application: build the central portion of the record from the lab.
• S3 diagnosis: find the first unsupported promotion in a plausible but invalid reconnaissance path.
• S4 decision: choose ACCEPT / MODIFY / REJECT / BOUNDED_DEFER and defend the choice with evidence and limitations.
• S5 transfer: work in the included second repository at assessment/transfer/FND004-S5_SECOND_REPO/; start from CHANGE_BRIEF.md, generate your own inventory and search trace, and rebuild the invariant questions under different naming/layout. No canonical anchor map is supplied.

S2–S5 are blocking. Copying paths from an example does not satisfy transfer; the changed context must produce new evidence.

Technical references and freshness boundary

Two tool-specific claims are bound to the official Git manuals:

• git ls-files is used only for its documented file-enumeration semantics around the index/working tree. It is not treated as an architecture authority.
• git grep is used only as a bounded pattern-search instrument. A text hit is not treated as proof of runtime execution.

Both sources were checked on 2026-09-02. This lesson relies only on their documented semantics for file enumeration and bounded pattern search; neither is treated as an architecture authority or proof of runtime execution.

Explicit non-claims remain: tracked does not mean executed; a search hit does not prove runtime dependency; the first plausible entry point is not automatically the active one; repository reconnaissance is not debugging.

Repository conventions vary across languages and build systems, so the transferable object in this lesson is the question/evidence method, not a universal directory layout.