The onboarding use case: how new engineers use a decision log on day one

Why the first week is always the same

New engineer onboarding has a predictable shape regardless of company size or stack. Week one is dominated by setup — environment, access, tooling — and by reading: the README, the architecture overview, the wiki pages that haven't been updated in eleven months. The engineer gets the system running locally. They make a small change, open a PR, get familiar with the review process.

Interspersed through all of this are the why questions. Why is authentication structured this way? Why does the API use this versioning convention? Why are these two services separate? Why is this feature behind a flag when everything else isn't? Why does the mobile client have a different API contract from the web client?

These questions don't get answered from the README. They're not in the wiki. Sometimes they get answered by the most experienced engineer on the team, who has to stop what they're doing to reconstruct an explanation from memory — which is itself an imprecise answer, because memory degrades and the original reasoning isn't what gets recalled, only the conclusion. Sometimes they get answered with "that's just how it is," which is the honest version of the same information gap.

The questions aren't about current behavior, which is what documentation usually covers. They're about historical choices — the fork in the road where the team evaluated options, picked one, and then moved on without writing down why. A new engineer needs to understand those forks to work in the codebase confidently. Without that understanding, they're navigating by implication: inferring intent from code shape, which is slow, or asking the team repeatedly, which is a tax on everyone else's time.

What wikis and READMEs systematically miss

It's worth being precise about the gap, because teams often assume that good documentation already covers it.

READMEs document current state and usage: how to run the app, what the environment variables mean, where the tests are. They're designed to get an engineer from zero to running, not to explain why the app is designed the way it is. A README answers "how do I use this?" A new engineer who reads it thoroughly knows how to develop against the system. They don't know why any of the non-obvious design choices were made.

Wikis document current process and current architecture. The architecture wiki page describes how the system works now — the services, the data flows, the integration points. It doesn't document the alternatives that were evaluated and rejected. It doesn't explain why the service boundary is here and not there. It doesn't capture the constraint that made a particular approach the right one. Wikis describe what exists; they don't describe what was ruled out. The ruled-out options are exactly what a new engineer needs to understand to avoid proposing architecture changes that have already been considered and rejected.

This is the gap that Architecture Decision Records and decision logs are designed to fill. An ADR is, by construction, a why document. It names the decision made, the alternatives considered, and the constraint that drove the selection. A new engineer reading an ADR gets the reasoning that produced the current design, not just a description of what the design is. That reasoning is what enables confident navigation — knowing that the API versioning convention is the way it is because of a specific mobile client backward-compatibility requirement tells the engineer not to casually suggest changing it, and tells them exactly what to check if a future change might affect it.

The specific questions new engineers always ask

These questions come up in nearly every onboarding, regardless of team or product. They map directly to the decision categories that belong in a log.

Why-this-technology questions. "Why Postgres and not MySQL?" "Why this ORM?" "Why did we build our own auth rather than using Auth0?" "Why Redis for this and not a database table?" Technology selection decisions are the most common ADR category, and they're the decisions most likely to affect a new engineer's early work. These questions are easy to ask and easy to answer — if the selection decision was recorded. Without a record, the honest answer is "we evaluated it at the time and this won out" delivered without any detail that would help the engineer assess whether the choice still applies.

Why-not-obvious-alternative questions. "Why isn't this a microservice?" "Why don't we use GraphQL?" "Why is the admin panel in the same codebase as the product instead of a separate service?" These questions are about architecture decisions — service boundaries, API design, deployment model — where the current design is clearly the result of a choice but the alternative is so obvious that the new engineer assumes it was considered. If it was considered and rejected, a decision record answers the question directly. If it was never explicitly considered, the question surfaces a gap: the team converged on the current design without ever formally evaluating the alternative, which means the new engineer's question is actually a useful probe. Sometimes the right answer is "we haven't thought about this carefully — let's write a decision record together."

Historical constraint questions. "Was this built this way on purpose, or did it just end up like this?" This is the most important category because it directly affects how confidently the engineer can work with the existing design. A choice that was made deliberately, with alternatives considered and a constraint driving the selection, is a load-bearing choice — changing it requires revisiting the constraint. A choice that accumulated through inertia rather than deliberation is not load-bearing in the same way. A new engineer who can't tell which category a given design element falls into is forced to treat everything as potentially load-bearing, which is the conservative position but also the one that slows down confident contribution. Decision records make the distinction explicit.

Rejection-record questions. "Have we ever thought about adding real-time sync?" "Did anyone consider GraphQL when the API was being designed?" "Why doesn't the mobile app have offline mode?" These questions map directly to the "not building this" records — the deliberate choices not to implement something, usually made after evaluating it and finding that the cost or complexity outweighed the benefit under the constraints that existed at the time. Without a rejection record, the new engineer doesn't know whether the question is settled (evaluated and rejected, with reasons that still apply) or open (never seriously considered, reasonable to propose). A rejection record with a clearly-dated constraint ("deferred pending mobile client API stability; revisit when mobile has a stable offline capability") tells the engineer exactly where the question stands.

How to structure a log for someone who doesn't yet know the codebase

Most decision logs are written for the team members who were present for the decisions. The titles reference code components, the context blocks assume familiarity with the existing system, and the alternatives are described using jargon that the team uses internally. This works for the team. It fails for a new engineer, who arrives without the internal vocabulary or codebase familiarity needed to locate a relevant record, let alone to understand why it's relevant to their current task.

Navigability for a new engineer requires two things: self-contained records and navigable entry points.

Self-contained records. Every ADR should name the component or system affected in plain language, not as a code path. "ADR-0031: Session storage approach for authenticated API requests" is navigable by a new engineer. "ADR-0031: AuthMiddleware.getSession() behavior" is not — it requires knowing the codebase well enough to have encountered AuthMiddleware before the record is findable. The context block should explain why this was a decision — what made it non-obvious, what alternatives were in play, what constraint was live at the time — without assuming the reader already knows why those alternatives were relevant. A new engineer should be able to read the context block and understand the decision landscape before they understand the decision itself.

The Nygard ADR format's Context section is specifically designed for this: "The context section describes the forces at play, including technological, political, social, and project local." Forces at play is the operative phrase — the record should describe the situation, not just the conclusion. A new engineer reading the forces at play section gets the constraint picture that produced the decision, which is the prerequisite for evaluating whether that constraint still holds.

Navigable entry points. A flat directory of numbered ADRs is hard to navigate for a new engineer who doesn't know which numbers are relevant to their work. Two structures help: tags by domain area, and a curated onboarding reading list.

Tags by domain area — auth, data model, API contract, deployment, third-party integrations, testing — create an entry point that doesn't require knowing how the code is organized. A new engineer assigned to work on authentication can find auth-tagged records without knowing where the auth code lives or how many ADRs exist. The same applies to the decision log template format, which is lighter-weight than full ADRs but should still carry domain tags to enable topic-first navigation.

The onboarding reading list

The highest-leverage onboarding move available to a team with a healthy decision log is a curated reading list: a short document (five to fifteen records) that every new engineer reads in their first week, selected for relevance to the overall system design rather than to any specific current task.

The reading list solves a real navigability problem. A team that has maintained a decision log for eighteen months might have forty or fifty records. A new engineer who receives access to the log on day one and is told to "read through it" faces a forty-five-minute task with no clear prioritization. The reading list answers: if you only read ten things, read these ten, because they explain the highest-level choices that constrain everything else.

A good reading list for a team with an established backend product typically includes:

• Data model shape decisions: Why is the data organized this way? What alternatives were considered? These are the decisions most likely to affect a new engineer's first real feature work, because nearly every feature touches the data layer.
• Authentication and authorization model: Usually one or two records explaining why the current approach was chosen and what alternatives were ruled out. This category generates the most repeated "why does it work this way?" questions because auth is often opaque from the code alone.
• API contract and versioning decisions: The choices that explain why the API surface looks the way it does — particularly the decisions that constrain what can change without breaking clients.
• Major rejection records: The two or three deliberate choices not to build something that are most likely to come up in early conversations. "We evaluated real-time sync in Q3 last year and decided against it because of the mobile client constraint — here's the record" is a better answer to that question than anything that can be said off the top of someone's head.
• Process decisions with context the team has forgotten: The code review policy decision that explains why PRs work the way they do, the deployment cadence decision that explains the release process. These are the decisions that confuse new engineers when team members enforce them without explanation.

The reading list is an onboarding artifact, not a selection for all time. It should be reviewed when it's used — after each new engineer has gone through it, a short conversation about which records were actually useful and which created more questions than they answered is a lightweight way to improve it over time.

First-week experience: with and without a log

The difference becomes concrete when you trace the same question through both scenarios.

Without a log. A new engineer discovers that the product API uses a non-standard pagination scheme — offset-based rather than cursor-based. She asks why. The most senior engineer on the team says it was a historical decision, the original API was built before the team got large enough to have a strong opinion, and cursor-based pagination was considered "too complex" at the time. When she probes further — is this something we could change? — the answer is "technically yes but there are mobile clients that depend on the current behavior." Two follow-up questions, twenty minutes of the senior engineer's time, and the answer is still incomplete: she doesn't know how many mobile clients, which versions, or whether the constraint is still live. She proceeds conservatively, treating the pagination scheme as load-bearing.

With a log. The same new engineer opens the API contract tag in the decision log. She finds a record from fourteen months ago: "Pagination scheme for the public API — considered cursor-based, chose offset-based for initial launch because of timeline constraint; mobile clients at v1.0 depend on offset behavior; revisit condition: when mobile has migrated past v1.0 at >90% of active users." She checks the mobile version distribution in the analytics dashboard. Mobile is at 97% on v2.x. She opens a decision record draft: "Proposal: migrate public API pagination from offset to cursor." She knows what to reference, why the original choice was made, and what the revisit condition was. The senior engineer spends ten minutes reviewing her proposal instead of twenty minutes reconstructing context from memory.

The delta is not just time. It's the quality of the outcome. The new engineer in the first scenario works with incomplete information and proceeds conservatively. The new engineer in the second scenario has the complete picture and can make a confident proposal. The decision log doesn't just save onboarding time — it enables confident contribution earlier, which is the actual value of a good onboarding experience.

Using extraction to recover the log that should have existed

Most teams that want to use a decision log for onboarding face a practical problem: the log doesn't yet exist, or it's thin relative to the age of the codebase. There are three years of architectural decisions in the system, and twelve records in the ADR directory. The new engineer reads all twelve in forty minutes and still has thirty unresolved why questions.

This is the problem that the WhyChose extractor addresses directly. The decisions that should be in the log often exist — they happened in AI chat, worked through by the engineers who were present — but were never transcribed to a record. A ChatGPT history export from two or three years ago contains the reasoning that produced the current architecture: the pagination scheme discussion, the auth library evaluation, the microservices-vs-monolith debate that ended with "not yet." None of it was written into an ADR. All of it is recoverable.

Running the extractor on historical AI chat exports — not just the most recent quarter, but the full history going back to when the product was being built — surfaces the decisions that should anchor the onboarding reading list. The resulting candidates, triaged through the standard triage workflow, produce a set of records that can be written as ADRs retroactively. The dating is accurate (the extraction preserves the original chat timestamp), the alternatives are recoverable (the chat contains the evaluation), and the constraint is usually explicit in the original reasoning.

A team that runs a six-month or two-year historical extraction before onboarding a new engineer is giving that engineer something that almost no documentation practice provides: the actual reasoning, not a reconstruction of it, from the people who made the choices. The reasoning was there all along. It just hadn't been moved to a format that onboarding uses.

The same applies to the everyday decision debt that compounds across quiet-log quarters. Each undocumented choice is a future onboarding cost — a question that will be asked without a good answer available. Running the extractor quarterly and maintaining the log through the triage workflow means that by the time the next engineer joins, the gap between "decisions that happened" and "decisions that are documented" is small.

When a new engineer disagrees with a recorded decision

A decision log creates a new scenario that teams without one don't face: the new engineer who reads a decision record and disagrees with it. This is actually a feature, not a problem, but it requires a small process to handle well.

The right response to a new engineer who reads a record and says "I think this was the wrong call" depends on the record's status. If the record is Accepted and the constraint that drove it is still live, the correct response is: "Here's why the constraint made this the right choice at the time. Do you think the constraint has changed?" This turns a disagreement into a productive constraint-review, which is exactly the mechanism the decision log is designed to support.

If the record is Accepted but its revisit condition has been met — the mobile clients are past v1.0, the team has grown past the size where the original process decision made sense — then the new engineer's disagreement is timely. The decision log makes this explicit in a way that undocumented decisions never can: the new engineer can point to the record, note that the revisit condition has been met, and propose a superseding decision with a clear audit trail. This is the supersede workflow working as intended, and it's notably more productive than a new engineer challenging a convention that nobody can explain.

If the record is from early in the product's life and the team suspects the reasoning no longer applies but nobody has updated it, the new engineer's challenge is a log-maintenance occasion. The right outcome is either a superseding record (if there's a new explicit decision) or a deprecation (if the decision is simply no longer operative). Either way, the new engineer's question produces a better log — a side effect that undocumented "why is it this way?" questions never create.

The day-one protocol

Concretely, this translates to a simple onboarding addition that teams can implement without process overhead:

1. Day one: share the reading list. Send the curated onboarding reading list (five to fifteen records) with the environment setup instructions. Frame it explicitly: "This is why the system is designed the way it is. Read these before writing any code. They'll answer most of the 'why is it this way?' questions you'll have in your first week."
2. Day two: walk through one record together. Pick the most relevant record for the engineer's first assignment and walk through it — context, alternatives, decision, revisit condition. This models how to read a record and establishes that the log is a live reference, not a historical archive that nobody consults.
3. Week one: log their first question. The first why question a new engineer asks that isn't answered by an existing record is the seed for a new record. Ask the engineer to draft it — briefly, using the standard ADR fields — as part of their onboarding. The draft gets reviewed and merged, and the engineer leaves week one having contributed to the log rather than just consumed it. This habit, established in week one, is how new engineers become active log maintainers rather than passive readers.

None of this requires a dedicated documentation system, a new tool, or a process meeting. It requires a decision log that exists and has enough records to be useful — which is the precondition that the quarterly triage workflow and the ChatGPT / Claude extraction process together provide.