What decision context should a new engineer get in week one?

Not the whole log. Give them the decisions they'll trip on first: the constraints governing the area they'll touch, the deprecated patterns that still appear in the code, and any temporary workarounds with review dates. Ten entries read in context beat a hundred read as homework.

How is a decision log different from onboarding docs?

Onboarding docs describe the system as it is and rot within a quarter. A decision log records why it got that way: each entry carries its reason and rejected alternatives, and reversals get successor entries. It stays useful because it's written at decision time, not documentation time.

What if we have no decision log and years of undocumented decisions?

Don't backfill the archive. You'll get it wrong and burn weeks. Start logging new decisions today, and backfill on demand: every time a newcomer's question uncovers an unwritten rule, that's the cheapest moment it will ever have to be written down.

How do we onboard engineers faster with decision context?

Onboarding is slow because new engineers must reconstruct why the system is shaped the way it is, and the code only shows what. Keep a decision log with reasons and rejected alternatives, link entries from the code they govern, and treat every 'why is it like this?' question as a missing entry to backfill.

Every codebase is full of decisions wearing no explanation: the ORM nobody likes, the service that talks through a queue for no visible reason, the naming convention that breaks in one directory. New engineers don't ramp slowly because the code is hard to read. They ramp slowly because the reasons are unrecoverable from the code.

Why onboarding is really slow

Peter Naur named the mechanism in his 1985 essay "Programming as Theory Building": a program isn't its source code. It's a theory held in the heads of the people who built it, and the code is a lossy record of that theory. Onboarding is theory reconstruction. The new engineer must rebuild, from artifacts and interviews, a mental model the original team holds for free.

Most teams run this reconstruction as oral history. The newcomer asks, a senior engineer answers from memory, and the answer evaporates. The next hire will ask the same question of the same person. This is why onboarding cost scales with hiring rate: the hallway is load-bearing, and every new person taxes it.

Code review makes the gap concrete. The newcomer submits a reasonable PR; a reviewer replies "we don't do it that way here." An unwritten rule just surfaced, and mostly it gets spoken once and stays unwritten.

What actually works

Keep a decision log with the why attached. Each entry: the verdict as one imperative sentence, the reason, the rejected alternatives, who agreed. The rejected-alternatives field is the onboarding gold: it's the difference between "we use JWTs" and knowing that Redis sessions were tried and rejected for operational cost, which is what stops the newcomer from proposing them in month two. The full format is in our decision log guide.

Link decisions from the code they govern. A one-line comment (// see decision #41: sync calls to billing are banned) puts the context where the confusion happens. Nobody reads a log as homework; everybody reads the link next to the weird code they're staring at.

Backfill on demand, at question time. Every "why is it like this?" from a new hire is a free audit: it has located a decision that exists only in heads. Write it down then, while the person who knows the answer is explaining it anyway. This is the cheapest capture moment there is. Spotify's engineers made the same observation about ADRs and review pushback.

Curate a first-week reading path. Ten decisions, in the order the newcomer will encounter them, scoped to the code they'll touch. Relevance beats completeness.

Give review dates to the temporary stuff. Half of what confuses newcomers is workarounds that outlived their excuse. A review date turns "mysterious permanent hack" into "known temporary call, revisit in March."

Where Lockstep fits

Lockstep builds this log without the filing: decisions get captured from Slack and Notion as they happen, owners approve them in one click, and every entry keeps its reason and history. New engineers get the why on demand, and so do the AI coding agents they work with over MCP, which face the same cold-start problem on every single task. Design-partner stage, Apache-2.0. See how it works.