A Repo Is Not An Onboarding Plan: How Teams Transfer Engineering Judgement

TL;DR: A repository gives a new engineer access to information, not judgement. I built an interactive first week path to make our team's decision-making visible, testable, and easier to practise. The aim was not faster reading, it was faster safe reasoning.

The Problem

When a senior engineer joins a team, it is tempting to give them access to the repository, point them at the documentation, and trust their experience to do the rest.

That is not onboarding. It is delegation.

Experienced engineers can read code quickly, but a mature codebase carries more than code. It carries local assumptions, operational history, testing habits, naming conventions, and a shared sense of what matters. Those are the things that help someone answer the real question: where do I look first?

That question is where engineering judgement lives.

The Shift

I started with a different objective. I did not want the first week to prove that someone had read the docs. I wanted it to give them a safe way to practise how the team reasons about the system.

The outcome looked like this:

That framing changed the work. The onboarding artefact became less about coverage and more about transfer. What judgement does the existing team already use? How can we make that judgement visible enough to practise?

The Example

The system I was working with was the Quality Evaluation Framework, which evaluates AI service behaviour from traces and experiment runs. Public readers do not need the internal details. The useful point is that it is a multi-part system where behaviour emerges across several boundaries: incoming events, background processing, storage, search projections, infrastructure, and a user interface.

That kind of system is hard to learn from a flat list of links. The approach also relied on a useful foundation: QEF already had enough documentation to turn into a guided path. In a less documented repository, the first onboarding task would be to build that map.

So I built a small GitHub Pages lesson plan inside the repository. Each day followed the same pattern:

flowchart LR
  A["Map the system"] --> B["Recall the flow"]
  B --> C["Inspect real files"]
  C --> D["Diagnose a failure mode"]
  D --> E["Make a small validated contribution"]

The path deliberately started from the engineer's existing strengths. General experience in Python, cloud systems, search, machine learning, frontend work, or production review was not the thing to teach. The thing to teach was the local decision model: which boundary matters, which file proves it, and which test gives confidence.

The Diagnostic Drill

The strongest part of the plan was a diagnostic exercise.

The scenario was small. An incoming event had been stored. The expected downstream result was missing. Some required metadata existed. Other routing metadata did not. No background job had been queued.

The question was: why did the result not appear?

That question is better than another overview page because it forces a sequence of decisions.

This is the judgement we usually transfer informally during pairing. We say things like "check the routing first" or "do not blame the worker until you know something was queued". Those phrases are useful, but they are often too late. The new engineer hears them only after getting stuck.

The drill moved that reasoning earlier. It taught the order of investigation, not just the shape of the architecture.

What AI Helped With

AI helped turn an intent into a concrete artefact. I could describe the outcome, provide repository context, and iterate quickly on the lesson structure, interaction model, and diagnostic scenario.

It accelerated the artefact. It did not decide what mattered.

Which failure mode matters? What evidence should count? Which local habit is worth teaching explicitly? Those are not content-generation decisions; they are engineering leadership decisions.

The Lesson

Onboarding is one example of a wider problem: teams need ways to transfer engineering judgement.

Documentation transfers facts. Pairing transfers context. Reviews transfer standards. A good onboarding path should combine all three, then give the new engineer a safe way to practise decisions before the stakes are high.

The model I would reuse is simple:

This does not remove the need for human support. It makes that support more useful. Instead of spending the first week explaining where every file lives, the team can discuss how the system behaves and how they know.

A repository tells people what the system is. Good onboarding teaches them how to reason about it.