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.
Physics enforced the old sequence. 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. It does all of that work in a system the person driving it could not draw on a napkin. The change often works, and the problem is what did not happen: no model formed, so the second week starts where the first did.
flowchart TB
subgraph before["BEFORE"]
direction LR
b1["need to change X"] --> b2["find X"] --> b3["read around X"] --> b4["model forms"] --> b5["change X"]
bnote["comprehension was the toll, and it was compulsory"]
end
subgraph now["NOW"]
direction LR
n1["need to change X"] --> n2["change X"]
nnote["model never forms, and nothing reports its absence"]
end
before ~~~ now
class b4 pass
class n2 warn
class bnote dim
class nnote block
This is not an argument for working without the agent. The argument is narrower: comprehension used to be free, and now you have to buy it on purpose. 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 may ask it anything, and you may not ship anything. That constraint is the entire design.
About 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 Wednesday ticket that makes you feel useful. The offer will come, and whoever makes it means well, but if you accept it the week becomes ordinary onboarding and no model forms.
The instinct is to read the source tree. That tree serves the people who already have the model.
The boundaries define a system's shape, not the 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. Then follow it from the entry point to the last write it causes, reading every layer it passes through. Following one trace beats a horizontal survey of any single layer. Only the trace shows how the layers relate, rather than what the directory names claim.
Choose the trace for centrality, not simplicity. The health check endpoint is easy and teaches nothing. Instead, pick the thing the business would notice within ten minutes if it stopped. The host chooses on that basis during their fifteen minutes on Monday.
A generated diagram lists everything. A model is a decision about what to leave out, and that decision is yours to make.
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 second draft, by contrast, has often had its uncertainty edited out. That uncertainty was the only thing on the page 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. The three kinds of question matter more than the count, because their reliability differs. Treat them as one kind, and you end the week misinformed and confident about it.
| 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 for a particular design is local and historical: an incident in March, a contract clause, a database that moved. That information is in commit messages, issues, and people. When the model supplies a plausible reason, 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. Keep the second map. Show the host both maps on Friday: the first one records 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.
Before you run anything, write down one prediction about behavior, specific enough that the run can prove it wrong. 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 mark is the honest part of the exercise, and it makes the result informative either way. Being right about a line you flagged as shaky is worth something. Being wrong about a line you were confident in is worth a great deal more.
A claim that comes back correct on every line was most likely too safe. The purpose is to find the edge of the model on a Thursday in week one, in a scratch environment. The alternative is 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. Their 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 host grades the map on honesty, not on completeness.
Hand over the list of every question the codebase could not answer. Every "why is this like this" with no answer in a comment, commit message, issue, or charter rule.
Only a new person can see what the documentation leaves out, and that ability lasts about three weeks. After that the gaps become invisible, not because anybody filled them but because the person stopped noticing. Every engineer who joins and does not write this list down has audited the codebase and then thrown the audit 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. Write it into the repo in exactly those words, or the next person spends 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 hold it. Most people lose about a third on the first attempt, and the lost third is informative. In most cases they copied it from the agent instead of tracing it 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, and it feels generous. The listener keeps almost none of it, because it arrives before there are any hooks to hang it on. The same two hours on Friday, answering questions the person generated, stick. Same information, same senior, opposite retention.
Every one of them is someone being helpful.
If you adopt one piece of the week, adopt Monday: one trace, entry point to last write, followed by hand. Monday takes ninety minutes and needs no host beyond picking the trace, yet it produces more usable model than the rest of the week combined.