Your onboarding is a mirror. Most teams don't like looking.

A new engineer joins. Somewhere in their first week, they hit the setup guide — and the setup guide is wrong. Not catastrophically wrong. Wrong in that specific, telling way: step four references a service that was renamed last year, step nine assumes access nobody has granted them, and there's a handwritten note from a previous victim saying "ignore this part, ask Priya."

Everyone laughs about it. I've stopped laughing about it, because I've realized what onboarding actually is: it's the only time your team's accumulated workarounds become visible. The rest of the year, everyone has adapted. The flaky test that "you just re-run." The deploy step "everyone knows" to do manually. The permission you request from a guy named in no document. Existing team members don't experience these as problems — they've internalized the detours so completely that the detours feel like the road.

A new person has no such adaptations. For about two weeks, they see your team the way an outsider sees it — which is to say, accurately. Then they adapt too, the workarounds become invisible to them as well, and the mirror clouds over until the next hire.

Which suggests treating those two weeks as what they are: a free audit you'd otherwise pay a consultant for.

The practice I push everywhere: the new person keeps a friction log. Every point of confusion, every doc that lied, every step that required interrupting a human — one line each, zero judgment, written in the moment rather than reconstructed later. This needs explicit framing, because new joiners default to assuming every problem is their fault and politely hiding it. Their confusion isn't a gap in them; it's data about you, and it expires fast.

Then — this is the part teams skip — someone senior actually processes the log. Fix the doc, automate the step, revoke the tribal knowledge by writing it down. An hour per hire, roughly. Do it for three consecutive hires and setup time typically collapses, because most onboarding pain isn't deep architecture; it's forty shallow cuts nobody ever aggregated. The first log kills the worst fifteen. Compounding does the rest.

There's a quieter payoff, too. The team that treats a newcomer's confusion as signal is teaching that person, in week one, that observations are welcome here — that "this seems harder than it should be" is a contribution, not an impertinence. That lesson shapes how they behave for years. The team that responds with "yeah, it's always been like that" is also teaching something, and it will also last for years.

And if you're between hires: you can rent the mirror. Have someone set up the project on a clean laptop, following only the written docs, no memory allowed. Order lunch for the team and watch. It's humbling, it's cheaper than attrition, and it's the closest a team gets to seeing itself from outside.

The onboarding is the team. Fix the reflection and you've fixed something real.