Map an unfamiliar repo from evidence, not guesses

OnboardingFreshModel-agnosticverified 2026-06-21sha 78cdcaf4c005

Born in: the post where it earned its place →

Breaks when: One traced journey is a thread through the maze, not the whole maze – it can miss entire subsystems (background jobs, error paths, alternate entry points, scheduled work) the chosen path never touches, so treat the map as a usable start, not a complete model. It weakens further on monorepos with several apps (one journey misrepresents "the" app), on generated-code or macro-heavy trees and dynamic dispatch where hops can look real but the semantics are not, and on plugin or dependency-injection systems where the wiring is resolved at runtime, not in the source. On a huge or undocumented repo with no clear build manifest, the agent can still mis-rank which entry point is "the main one." And a quoted file:line citation only proves a line exists and was opened, not that it was understood correctly – a confidently wrong reading quotes just as cleanly as a right one. This prompt does not verify runtime behavior unless execution is separately authorized.

Vendor “explain this codebase” prompts give you a fluent prose tour that is half pattern-matched from directory names and framework defaults – confident, readable, and wrong in exactly the places that bite. This one forbids that: it stays strictly read-only, reads the governance docs before guessing, derives the real entry points from the build files instead of the folder layout, traces ONE actual journey end-to-end with a quoted file:line snippet at every hop, and marks anything it did not directly open as INFERENCE. The output is not an essay, it is a change-oriented index – “to change X, start at Y” – plus the dependency hotspots to touch carefully.

You are onboarding to a repository you have never seen. Your job is to produce a navigational MAP grounded in evidence, not a prose tour pattern-matched from folder names. A confident description built from naming conventions instead of read code is a failure of this task.

Repo to map:
{{repo_path}}

What I am most likely about to change:
{{change_intent}}

READ-ONLY / DESTRUCTIVE-ACTION GATE (applies to every phase)
- This task is read-only. You map the repo, you do not change it or run it.
- Do NOT create, edit, delete, move, rename, or format files; do NOT install, upgrade, or remove dependencies; do NOT run migrations, codegen, or formatters; do NOT start build scripts, tests, package managers, Docker, framework CLIs, or any long-running service; do NOT change git state (no commit, checkout, stash, reset, branch).
- Allowed: open and read files, list directories, search text, and inspect git status/log/diff without mutating anything.
- Do not run project code to "see what it does." If a question can only be answered by executing something, record it as an open question for the human, do not execute it.
- If a command might write files, touch an external service, change a database, alter dependencies, or start a persistent process, STOP and ask before doing it.
- If you are unsure whether an action is destructive, treat it as destructive and do not do it.

ANTI-GUESS RULE (governs everything below)
- Every claim is either FACT or INFERENCE. A FACT requires that you directly opened the file and can quote the relevant 1-3 lines, with a path:line citation and one clause on what those lines prove. If you cannot quote the line, it is not a FACT - downgrade it to [INFERENCE]. Label inferences inline as [INFERENCE]. Never present an inference as a fact.
- Phrase every FACT no stronger than the quoted line actually proves. "package.json line 14 defines script dev -> next dev" is a FACT. "this is the app's main runtime path" is a stronger claim that the single line does not prove - it needs a cited chain. Causal, centrality, and dependency claims ("A calls B", "X is central", "Y depends on Z") require a cited evidence CHAIN (the call site, the imported symbol, the receiving file), not one nearby line.
- If you cannot establish how two parts connect by reading actual code, say "connection unverified" and name the file you would need to read to confirm it. Do NOT invent the wiring, and do NOT bridge the gap with a naming convention.
- Naming conventions are a hypothesis, not evidence. A folder called "auth" is a clue to read it, not proof of what it does.

PHASE 1 - GOVERNANCE FIRST (read before forming any opinion)
Read, if present: CLAUDE.md, AGENTS.md, CONTRIBUTING, README, ARCHITECTURE / docs/architecture, ADRs. Do not stop at the README - open the architecture and contributor docs too if they exist. From these, record:
- The canonical sources of truth the project itself names (which files/dirs are authoritative, which are generated, which are deprecated).
- Stated conventions, invariants, and "do not touch" zones.
- Anything the docs claim that you will later want to verify against the actual code.
If governance is missing or thin, say so explicitly - you are now mapping with less ground truth and more inference.

PHASE 2 - REAL ENTRY POINTS FROM THE BUILD, NOT THE FOLDERS
Read the build/config/manifest files (package.json, pyproject.toml, go.mod, Cargo.toml, Makefile, Dockerfile, CI workflows, framework config). From these, derive:
- The actual tech stack and language(s), with versions where stated.
- The repo TYPE, from evidence, not assumption: web/app service, CLI, library/SDK, worker or data pipeline, infrastructure/config, monorepo with multiple of these. This decides what counts as an entry point and what a "journey" is later.
- The REAL entry points: the scripts, main()/bin, server bootstrap, route roots, or job runners that the build/run commands actually invoke. Distinguish what the build INVOKES to run the thing from what it merely BUILDS, lints, or checks - a lint script or a test runner is not the app's entry point.
Present the entry points as a ranked table. Rank ONLY by stated signals, each with a path:line citation: the default run/start script, the production container CMD/ENTRYPOINT, the CI deploy or release job, the documented primary binary. Do not rank by which filename "feels central" (main, index, app). If two entry points are tied on evidence, say so rather than inventing a winner. On a large or undocumented repo, flag that this ranking may be wrong.

PHASE 3 - LAYERS AND DEPENDENCY DIRECTION
Partition the code into responsibility layers by the package/import graph and build targets, NOT by top-level folder names (src/, lib/, internal/, flat repos, and monorepo packages/* all break a folder-name partition). If the directory layout is misleading, state the partition rule you used in one line and cite the file that justifies it. For each layer:
- One line on what it is responsible for, grounded in the specific files you opened to represent it - name them and say why they are representative, so the layer is not inferred from one convenient file.
- State the dependency DIRECTION between layers (which depends on which). For each inter-layer edge you assert, cite at least one real import: the importer path:line -> the imported file, with the symbol that crosses. An edge with no cited import is [INFERENCE].

PHASE 4 - TRACE ONE REAL JOURNEY END-TO-END
Pick ONE concrete journey appropriate to the repo TYPE from Phase 2:
- web/app: a request or UI action; CLI: a command invocation to its output or side effect; library/SDK: a public API call into the core behavior; worker/data: a scheduled job or pipeline step to its emitted artifact; infra: a declared entry command to the provisioned or planned change.
Choose the journey closest to {{change_intent}}. If {{change_intent}} is vague, list 3 candidate journeys with evidence and pick the most central non-trivial one. Do NOT pick a health check, homepage render, smoke test, or CLI help path unless that is the stated intent - those are the easy happy paths that look complete while dodging the real subsystem. Name the journey in plain language ("user submits the form and the record is saved"). Then trace it through the ACTUAL call path, hop by hop:
- At EACH hop, do one of two things and nothing in between: (a) quote the 1-3 lines that show control arriving and the call that passes it onward, with path:line and a clause on what they prove; or (b) if the hop goes through indirection you cannot resolve by reading (dynamic dispatch, dependency injection, a registry, config-driven wiring), STOP the hop list, say "connection unverified" and name exactly where you lost the thread. Never invent the next hop to keep the chain looking complete.
- A valid end-to-end trace must reach a real terminus: a response, persisted state, an external call, an emitted artifact, or an explicit side effect. If you cannot reach one, label the result PARTIAL TRACE, not end-to-end, and say where it stops.
This single trace is a thread through the maze, not the whole maze. Explicitly list what it did NOT cover: other entry points, background/scheduled jobs, error and retry paths, alternate flows.

PHASE 5 - OUTPUT (the deliverable, in this order)

## Stack and entry points
Tech stack, repo type, and the ranked entry-point table - each row with the build-file evidence (path:line) that proves it and what signal it ranks on. Note ranking confidence.

## Architecture map
The layers and the dependency direction between them. One grounded line per layer (name the files that represent it). Each inter-layer edge carries a cited import (importer path:line -> imported file, symbol). Unverified edges marked [INFERENCE].

## Traced journey: <name>
The end-to-end hop list with a quoted snippet + path:line at every hop, ending at a real terminus (or marked PARTIAL TRACE). Then "Not covered by this trace:" listing the subsystems and paths it skipped.

## To change X, start at Y
Lead with {{change_intent}}. The traced journey should intersect it where possible; for that area give the first file to open, the function/region to touch, and the layers a change there will ripple into - all as cited FACTs. For up to two OTHER likely change areas not on the trace, give the first file to open only, marked [INFERENCE]; do not assert ripple effects you did not trace. Concrete paths only.

## Danger zones
A danger zone is a module that meets a stated threshold, not one that "feels core": it has >= 3 distinct importers OR it sits on the traced journey AND is imported by 2+ layers. For each, give the import/reference count or list the top 3 importers with path:line. If you did not run an import scan, say "import scan not performed" and mark the load-bearing claim [INFERENCE] rather than guessing fan-in from the name.

## Confidence and gaps
- Where governance docs disagreed with the actual code (code wins - say which).
- The single biggest thing you are unsure about and exactly which file would resolve it.
- One honest line: this map is a usable starting point, not a complete model - name what is most likely missing.

HARD RULES
- Stay read-only. You never mutate the repo, run its code, or change git state. If something can only be answered by executing, record it as an open question.
- A FACT requires a path:line you actually read AND a quoted 1-3 line snippet. If you cannot quote it, it is [INFERENCE]. No exceptions.
- Phrase every claim no stronger than the quoted line proves. Centrality, causality, and dependency claims need a cited chain, not a single nearby line.
- Trace exactly ONE journey fully rather than describing five shallowly. Depth with citations beats breadth from guessing. Stop the chain at the break instead of inventing the next hop.
- Never describe behavior from a file's name alone. If you did not open it, you do not know what it does.
- Report findings here, in your output. Do NOT create side-channel task chips or spawn background tasks.

Fill in: repo_path change_intent

Shared as is, for reference. Read it and decide what it will do before you run it; using it is your responsibility, under the terms.