Your Codebase Isn't the Hard Part of Onboarding

Ramp-Up Is the Most Expensive Thing You Buy

When you bring in someone external, you pay for onboarding twice.

You pay for their time while they're not yet useful. And you pay, more expensively, in your senior engineers' attention, because the only way the new person gets context is by interrupting the three people who already have too much to do. The people best equipped to answer questions are always the people who can least afford to.

The standard advice for the first ninety days is: ask questions, take notes, shadow people, be patient. It's fine advice. It's also slow, and it depends on holding a thousand half-understood things in your head simultaneously with none of it written down anywhere.

I do something different. I've used it on two engagements now. That is a useful case study, not a benchmark, but both times it helped me form useful questions before I had enough context to ask them unaided.

Day One: Build the Corpus

Not read. Ingest. I'm not trying to read your entire codebase on day one. I'm trying to find the shape of the organization.

The sources we agree are relevant go into a local retrieval system:

• The codebase, cloned locally
• Internal documentation, wherever it actually lives, which is usually three places
• The ticket board, exported to JSON and ingested
• Approved project channels, when their history is relevant to the work
• Architecture diagrams, typically scattered, typically out of date, still better than nothing
• Any meeting notes anyone bothered to save

The corpus and index stay inside the client environment. Before anything runs, the ingest plan also names every model or external service involved, if any, so "local" does not conceal a network call. The system is disposable when the engagement ends.

Mechanically it's the same move I've written about at single-repo scale (put the graph in a file next to the code and query it) just pointed at an organization instead of one project. Extract, look at the shape, ask it things. Nothing here needs a server stood up or a platform bought.

Two Different Questions, Two Different Tools

Worth separating, because conflating them is why this kind of effort often disappoints.

Some of my questions are structural. What talks to what? What depends on this service? What would break if we changed it? A graph gives me stronger evidence for those relationships than similarity search alone. Asking a retrieval system "what depends on the billing service" may return documents that mention the billing service, which is not necessarily the same thing.

Others are semantic. Which operational problems recur without becoming tracked work? What does "done" mean here? Those questions live in prose, and retrieval is usually the better starting point.

A real picture of an organization needs both, and the mistake I see people make is picking one and then being disappointed that half their questions come back mushy. Structure tells you how the system is wired; prose tells you how people feel about it. The interesting findings are almost always where those two disagree: where the architecture says one team owns a thing and the chat logs say nobody does.

What I Won't Ingest

Worth saying plainly, because it's the second question every client asks after "does this leave our network."

I ingest what my access and the agreed purpose cover, and nothing else. If I can't legitimately read it as a person on day one, it doesn't go in the corpus. A retrieval system is not a way to launder access I wasn't granted. Payroll, HR files, private conversations, anything under a compliance boundary, and customer data that isn't already part of the work are out by default. This is for understanding systems and recurring work, not evaluating individual employees.

The practical version is that I hand over the ingest list before I run it. It names the sources, purpose, processing boundary, retention, and deletion plan. That converts "the consultant vacuumed up our systems" into a scoped decision somebody actually made.

Then I Ask It the Questions I'd Otherwise Ask Your Team

These are the questions that normally cost you a week of senior engineers' calendars:

• What is the product, actually, as opposed to how it's described externally?
• Where does the data live, and what talks to what?
• What is the board actually tracking?
• Which operational problems recur in project channels without becoming tickets?
• What does "done" mean here, in this codebase, versus in this company, versus to this customer?

That fourth one is often the valuable one. Organizations develop a gap between the problems they track and the problems people repeatedly work around. Project history can make that gap visible, but it produces a lead to verify, not a verdict about the team.

The thing that makes this work isn't any single question. It's beginning with a broad first pass. This is tracer-bullet work: ask across the corpus, see which answers have useful sources behind them, then investigate those paths. It reduces the ordering problem when I don't yet know enough to choose the perfect first question.

Week one starts in expansive mode. The first map is a set of sourced hypotheses, not an authoritative model of the company. Every consequential finding gets traced back to its source and checked with the people closest to it. The advantage is asking them three precise questions instead of thirty introductory ones.

What It Surfaced Both Times

Across the two engagements where I've used this approach, two categories appeared early:

The roadmap-versus-reality gap. Ask "what has this team most recently been asked to do?" alongside "what does the roadmap say they're working on?" and compare. When those diverge, it may simply mean the roadmap predates several urgent requests. Reading both sources together made that drift visible in the first few days.

Ownership ambiguity. The pattern is a service associated with several teams but clearly claimed by none. Repeat incidents and contradictory documentation can reveal that pattern, but only the affected teams can confirm whether the ownership gap is real.

Neither signal requires deep system knowledge to notice. Turning either one into a finding still requires source checking and a conversation with the people involved.

The Part I Didn't Expect: It's a Social Artifact

Building this visibly changes how people treat you, and faster than competence alone would.

People notice you're building something. Then they watch it return a useful answer with citations to their own documentation, and they help confirm or correct it. That produces a specific kind of credibility: not "this person knows about AI," which is cheap and everyone claims it, but "this person did the homework and knows what still needs checking."

For an outside consultant, that shortcut matters more than it would for an employee. You have a narrow window to be taken seriously before you're categorized as overhead, and demonstrating you've done the homework beats asserting it.

Build It For the Team, Not Just Yourself

This is the correction I'd make to how I did it the first time: I built the thing for my own head, and I should have handed it over.

The team would have found it useful. They had the same questions I did. They'd just stopped expecting answers, because searching four systems is nobody's idea of a good afternoon. I had the corpus assembled and never offered it.

Now I treat it as a deliverable. The engagement ends with a system your team can keep asking questions of, along with the ingestion scripts to refresh it. That converts a consultant's private advantage into something that outlives the consultant, which is what you were actually paying for.

Findings Belong in the Repo, Not the Report

Here's the failure mode of this kind of work, and it has nothing to do with the technique: you produce an excellent document, everyone nods, and eighteen months later the same problem is back because the document is in a folder nobody opens.

A slide deck is not durable. Where possible, findings should land as something that fires on its own: a tripwire instead of a bullet point.

Concretely: if I confirm that a service breaks whenever a particular field is empty, the deliverable isn't "we recommend validating this field." It's a failing test with a name that explains the constraint. If two teams resolve a disagreement about who owns a service, the agreed decision belongs in CODEOWNERS and alert routing, not only in a paragraph about the ambiguity.

The distinction is whether the finding survives me leaving. A recommendation depends on someone remembering it. A test keeps enforcing the decision, and its failure message can re-explain the reasoning to whoever trips it in two years.

Not everything converts. "Your roadmap and your team's actual instructions have drifted" isn't a test. It's a conversation with people who have authority. But a surprising amount does, and the portion that does is the portion that's still working after the engagement ends.

The Honest Caveat

Finding problems fast is not the same as having authority to fix them.

This method helps me form useful hypotheses in days instead of waiting months for context to accumulate. It does not replace learning the system, and it does not get an organization to act on what it finds. That depends on whether the person who commissioned the work and the team who'd have to change share the same picture of success. When they don't, no amount of good analysis closes the gap. I've watched a tool work fine and get adopted by nobody, because adoption was a permission problem rather than a quality one.

Which is its own argument for doing discovery in week one instead of month three. If those pictures don't match, you want to find out while it's still cheap to fix, and an engagement is a much better place to discover it than a hire.

What This Means If You're Hiring Someone

The relevant question isn't how many years someone has in your stack. It's how fast they build an accurate model of your environment, and how much of your team's time they consume doing it.

My goal is useful questions in days, followed by targeted validation with the team. The deliverable is a sourced system map, a validated findings list, and the scripts and instructions needed to refresh or delete the corpus without me.

That's the shape of the work I take on through JustinTime Systems. If your team is carrying a process nobody has been able to examine across code, documentation, and day-to-day work, that's the engagement.

Header photo by Susan Q Yin on Unsplash.