Unfamiliarity used to be self-limiting. You could not produce a plausible change to a system you had not read, so reading happened whether or not anyone planned it. That is no longer true, and the first casualty is the week where a new engineer built a model of the thing. This exercise puts that week back and gives it deliverables: one trace, one map you draw by hand, twenty questions, and a claim you have to defend on Friday.
Nobody designed the first week. It worked anyway, because producing anything required understanding something first.
The old sequence was enforced by physics. To change a function you had to find it, and to find it you had to learn the layout. To make the change compile you had to learn the types. To make it pass you had to learn what the tests believed. None of that was a curriculum. It was the toll you paid on the way to your first merged change, and everybody paid it.
The toll is now optional. An agent will locate the function, match the surrounding style, satisfy the types, and get the suite green, in a system the person driving it could not draw on a napkin. The change is often fine. The problem is what did not happen: no model got built, and the second week starts from the same place as the first.
BEFORE
need to change X ──▶ find X ──▶ read around X ──▶ model forms ──▶ change X
comprehension was the toll, and it was compulsory
NOW
need to change X ──▶ change X
model never forms, and nothing reports its absenceThis is not an argument for working without the agent. It is an argument that one specific thing which used to be free now has to be bought on purpose, and that a week is a fair price for a system you will work in for two years.
For one week the agent is a comprehension instrument, not a production instrument. You are allowed to ask it anything and not allowed to ship anything. That constraint is the entire design.
Roughly ninety minutes a day. The rest of the week is whatever onboarding you already do.
No production changes this week. Not a typo fix, not a dependency bump, not the small ticket somebody offers you on Wednesday to make you feel useful. The offer will come, it will be kindly meant, and accepting it converts the week back into ordinary onboarding, where the model does not get built.
The instinct is to read the source tree. The source tree is organised for the people who already have the model.
A system's shape is defined at its boundaries, not in its middle. Before opening any business logic, answer two questions: where does data get in, and where does it get out. Everything between those is detail you can acquire later, and most of it you never will, correctly.
Pick one real request or job with the host. Follow it from the entry point to the last write it causes, reading every layer it passes through. One vertical slice beats a horizontal survey of any single layer, because it is the only way to learn how the layers actually relate rather than what the directory names claim.
Choose the trace for centrality, not simplicity. The health check endpoint is easy and teaches nothing. The thing the business would notice within ten minutes if it stopped is the right pick, and the host should be choosing it on that basis in their fifteen minutes on Monday.
A generated diagram lists everything. A model is mostly a decision about what to leave out, and the leaving out is the part you have to do yourself.
You could ask the agent for an architecture diagram in ten seconds, and it would be accurate, comprehensive, and useless. Accurate because it can read every import. Useless because a map of everything has no viewpoint, and a viewpoint is what you are trying to acquire. Drawing it badly, by hand, forces the only question that matters: what is central here?
Do not tidy it. A map with three crossings out and a question mark in the corner is doing its job; a clean one drawn on the second attempt has usually had its uncertainty edited out, which is the only information it contained that nobody else already had.
Unlimited questions produce a transcript. A budget produces a decision about what you actually do not know.
Twenty is arbitrary and the arbitrariness is fine; scarcity is the mechanism, not the number. What matters far more is that the three kinds of question have wildly different reliability, and treating them as one kind is how people end the week confidently misinformed.
| Kind | Example | Reliability | What to do with it |
|---|---|---|---|
| Where | "Where is the retry policy applied?" | High | Take it. Then open the file, because the answer is a pointer and not a fact. |
| What | "What does reconcile() do?" |
Mostly | Use as a reading aid. Read the function afterwards and check the summary against it. |
| Why | "Why does this bypass the queue?" | None | Never accept. Go looking in the repo. If the repo cannot answer, it is a gap (§6). |
The agent will answer them, fluently, in the same register as the other two. But the reason a particular thing is written a particular way is local and historical: an incident in March, a contract clause, a database that used to be somewhere else. That information is in commit messages, issues, and people. When the model supplies a plausible reason instead, you have acquired a false belief that will feel like knowledge for months.
Spend the budget on the question marks from Tuesday, mostly on where. Then redraw the map. The second map is the one you keep, and comparing it to the first is a useful thing to show the host on Friday: it shows what you thought the system was on Tuesday.
A model you cannot test is a feeling about a system. Thursday converts it into something with an outcome.
Write down one prediction about behavior, specific enough to be falsified, before running anything. Then run it.
CLAIM
If I submit an order with two line items and a discount code
that has already been redeemed, then:
· the order is created ← I think
· no discount row is written ← I think
· the customer sees the full price ← I think
· nothing is logged at warn or above ← least sure
RESULT
✓ order created
✓ no discount row
✗ customer saw the discounted price anyway ← model was wrong
✓ nothing logged
WHAT I HAD WRONG
Price display reads a cached total written before validation.
The cache is a box I did not have on my map at all.Mark the line you are least sure about before running. That is the honest part of the exercise and it is what makes the result informative either way: being right about the thing you flagged as shaky is worth something, and being wrong about a line you were confident in is worth a great deal more.
A claim that comes back entirely correct usually means it was too safe. The purpose is to find the edge of the model on a Thursday in week one, in a scratch environment, rather than in March in production.
Thirty minutes. Twenty of them are the map, and ten are the most valuable list nobody collects.
Walk the host through it, then let them ask. The useful questions are all of one shape: point at an arrow and ask what flows across it, point at a box and ask what happens when it fails. Anything answered with "I think" gets circled, and circles are a fine result. The map is being graded on whether it is honest, not on whether it is complete.
Hand over the list of every question the codebase could not answer. Every "why is this like this" with no answer in a comment, a commit message, an issue, or a charter rule.
A new person is the only one who can see what is undocumented, and the ability lasts about three weeks. After that the gaps become invisible, not because they were filled but because the person stopped noticing them. Every engineer who joins and does not write this list down is an audit of the codebase that was performed and then thrown away.
The host owes an answer or an admission on each item, that day. "Nobody knows, it predates all of us" is a legitimate answer and should be written into the repo as exactly that, because the next person will otherwise spend the same afternoon on it. This is where the exercise pays rent back to the codebase rather than only consuming senior time.
One test, five minutes, and it is not negotiable with yourself.
Put the map face down. Redraw it from memory on a blank sheet, five minutes, no looking. Then compare.
What survives the redraw is your model. What does not survive was a diagram you made, which is a different thing that feels identical while you are holding it. Most people lose about a third on the first attempt, and the third they lose is informative: it is usually the part they copied from the agent rather than the part they traced by hand.
Redraw the trace path and the boxes it touches, from memory, correctly. Not the whole system. The one path you followed on Monday, and what it touches, is a fair definition of having arrived.
The host's main job is resisting the urge to give a tour.
The two-hour whiteboard walkthrough is the default, it feels generous, and almost none of it is retained, because it arrives before there are any hooks to hang it on. The same two hours spent on Friday, answering questions the person actually generated, lands completely differently. Same information, same senior, opposite retention.
Every one of them is someone being helpful.
If you adopt one piece of this, adopt Monday: one trace, entry point to last write, followed by hand. It is ninety minutes, it needs no host beyond picking the trace, and it produces more usable model than the rest of the week combined.