New Engineer Onboarding Agent: Compress the First 90 Days to 3 Weeks

The senior engineer you just hired is not confused because they are incompetent. They are confused because the context they need to operate is distributed across systems that were never designed to be read by anyone other than the people who built them. Old PRs. ADR files three migrations behind. Slack threads from 2024. The heads of three engineers who joined before the Series B.

The questions are predictable: why did we build it this way, where does this service talk to that one, what should I actually work on first. The answers exist. They are just not retrievable.

This is an indexing problem, not a documentation problem. The onboarding agent does not write new docs. It extracts the reasoning that is already in the system — PR comments, post-mortems, ADRs, incident channels — and structures it for someone encountering the codebase cold. Three layers, each targeting a question the new hire is actually asking on a specific day of their ramp.

One agent is not enough. The questions a new hire asks on day one are different from the ones that show up on day fifteen, and the same retrieval pipeline cannot serve both well. Layer 1 hands over the map. Layer 2 explains why the map looks the way it does. Layer 3 picks the first move. Run sequentially, each layer narrows the surface area the next one has to cover.

The orientation agent runs against every repository the new hire will touch and produces a service brief per repo. This is not the README rewritten by a model. The README is an input — usually a stale one — among several.

For each service, the brief carries four things:

What it does. A two-paragraph plain-language description derived from README, API surface, and route handlers. If the README has not been touched in six months, the agent flags it and falls back to code-level analysis.^[1] Stale documentation with no freshness signal is worse than no documentation — it manufactures false confidence.

How it connects. A dependency map extracted from imports, API client configurations, and infrastructure-as-code. What this service calls. What calls it. What shared state it touches. The map is generated, not maintained — drift is not possible because nobody owns it manually.

Where the load-bearing files are. A guided tour of the directories that matter, weighted by commit frequency over the last 90 days. Files that change often are files the new hire will touch. Stable utility code can wait.

Who actually owns it. CODEOWNERS plus the most active contributors in the last 90 days plus the on-call rotation. The right answer to 'who do I ask' is a name, not a team channel.

The most expensive sentence in any onboarding conversation is 'there's a reason for that, but nobody remembers exactly what it was.' The reason exists. Some senior engineer typed it out two years ago in a PR review or an incident channel and then closed the tab. Layer 2 indexes those typings.

Three sources, ranked by signal density:

Architecture Decision Records. Where they exist, ADRs are the highest-density context source the team produces. The agent parses every ADR, links each decision to the services and code paths it affects, and surfaces them on lookup.^[4] AWS's prescriptive guidance — drawn from more than 200 real ADR cycles — notes that teams spend material time re-litigating decisions that were already made and documented, simply because the documentation was never tied to the code it governed. When the new hire asks why the notification service polls instead of taking webhooks, the answer is the 2024 ADR, not a Slack ping to the senior on call.

PR review threads. The richest source most teams have, and the most under-indexed. Significant PRs — 8+ review comments, multiple revision cycles, large diffs — carry inline arguments about tradeoffs, rejected alternatives, and the failure modes the author is defending against. The agent indexes those discussions and ties them to the files they touch.

Post-mortem documents. Defensive code looks excessive until you read the post-mortem. The retry wrapper that wraps every external call has a date attached to it: the cascading timeout in 2024 that took the payment pipeline down for three hours. The agent links recommendations to the diffs that implemented them so the new hire reads code with the scar tissue visible.

Most onboarding knowledge base attempts use a single vector store and call it RAG. This works well for recall — 'show me something about the payment service' — and poorly for reasoning — 'why does this file exist and why does it look the way it does.' The queries that matter during onboarding skew heavily toward the second type.^[7]

A more robust setup uses three retrieval modes and routes between them:

Semantic retrieval (vector similarity) handles 'what is X' and 'show me examples of Y' — the orientation questions that dominate Layer 1. The embedding model indexes file content, README excerpts, and service summaries. Chunk size matters here: 512-token chunks with 64-token overlap work better than naive paragraph splits because code spans multiple logical units that natural paragraph breaks will cut through.

Keyword + path retrieval (BM25 or exact match) handles 'find the ADR that changed the auth flow' or 'show me context for src/payments/retry.ts'. File path matching is the highest-precision signal when the new hire is already looking at specific code. Hybrid search — combining semantic and BM25 scores with Reciprocal Rank Fusion — outperforms either alone by a meaningful margin on the 'explain this file' queries that Layer 2 needs to answer.

Graph traversal handles 'trace this decision forward' — starting from an ADR and following which files changed, which incidents referenced the same pattern, and which subsequent ADRs superseded or modified the original decision. The dependency map from Layer 1 becomes the graph; each ContextEntry's relevantPaths are edges. This is the retrieval mode that no embedding model replaces.

The routing logic is straightforward: path present in the query → keyword + graph. No path but a time reference → BM25 with date filter. Freeform question → semantic + rerank. Start simple. The failure mode of over-engineering the router before the index has real content is spending two sprints on architecture and shipping nothing.

Most teams botch the starter ticket. Either it is so trivial it teaches nothing — fix a typo in a doc nobody reads — or it is so sprawling the new hire spends three weeks understanding why the architecture is the way it is before they touch a line of code. The right starter ticket sits in a narrow band: meaningful enough to force engagement with the codebase, scoped enough to ship in two to three days, and connected to something the team will actually merge.

The matching agent takes three inputs and returns a ranked list:

Sprint context. Current backlog, team velocity, upcoming deadlines. The agent surfaces tickets that are needed but not on the critical path — work the team wants done but will not block the sprint if the new hire takes longer than expected.

Skill profile. Stated experience with languages, frameworks, and domain areas, captured during the interview process or a structured intake. A frontend specialist does not get a Kubernetes networking ticket on day three. This is not a kindness. It is a calibration of where the new hire's existing context actually transfers.

Codebase accessibility. From Layer 1: which services have current documentation, the highest test coverage, and the most active reviewers. The agent biases toward those. The first ticket lands where the safety net is densest.

Output is a ranked list of three to five tickets, each with the rationale attached: what the new hire will learn, which services the change will touch, who they should pair with on review.

The most valuable onboarding artifact is not a document anyone wrote. It is the by-product of every team's daily communication that nobody curated for onboarding. The agent harvests this passively — no new process, no one drafting onboarding wikis on top of their actual work.

PR comment mining. Review comments are direct links between code patterns and operational scars. When a reviewer writes 'use the existing retry wrapper — last time someone rolled their own we got the cascading timeout from INC-2847,' that comment is a pointer from a code line to an incident. The agent indexes those pointers.

Slack thread analysis. Project channels carry decision narratives that never become formal docs. The agent scans threads with high engagement — many participants, many messages — in channels tagged to the new hire's team, extracts the decision, and links it to the relevant code or ticket.

Incident context. Post-mortems document what broke. The richer context lives in the incident channel itself: the hypotheses that were tested and rejected, the workarounds that became permanent, the assumptions that turned out to be wrong. The agent indexes the channel transcript alongside the formal write-up.

All of this runs continuously. By the time the new hire signs their offer, the index is already populated with months of institutional knowledge.^[3]

A caveat that cost us a sprint to learn. The first version pulled every PR comment indiscriminately. Result: noise. Snarky review banter, debates from a pre-migration architecture, context tied to code that had since been deleted. The index is only as useful as its filter. The threshold that worked for us: 8+ review comments, 2+ participants, merged within the last 18 months. Older PRs are excluded unless they touch infrastructure that has not changed. The filter is not optional. It is the product.

Every team that builds this system makes roughly the same mistakes in the same order. Here is the sequence:

Indexing too much, filtering too little. The first instinct is to ingest everything — all PRs, all Slack channels, all doc pages. The index balloons. Query latency climbs. Retrieval quality collapses because the signal-to-noise ratio is 1:20. The fix is not a better embedding model. It is the filter. Enforce the thresholds before you build the retrieval layer.

Treating the service brief as documentation. The brief is context for someone unfamiliar with the system. If engineers start citing the brief as the authoritative source — instead of the actual code or the ADR — you've created a new stale layer on top of the old stale layer. The brief regenerates weekly and carries no normative authority. The code is the source of truth. The brief is a reading guide.

Wiring the Slack scanner to DMs or private channels. This happened at two organizations I'm aware of. The immediate reaction from the engineering team was correct: the scanner got shut down, the trust damage took months to repair, and the whole project was set back. Public engineering channels only. The list is a config file checked into the repo. Any engineer can audit it.

Shipping Layer 3 before Layer 1 is accurate. Starter ticket matching generates visible output fast, which creates pressure to ship it first. Resist. A miscalibrated skill profile combined with an inaccurate service brief produces a ticket recommendation that is actively harmful — it lands a new hire in the wrong part of the codebase with the wrong frame for what they're looking at. Get the orientation brief right first.

Not measuring time-to-first-PR before deploying. The metric that validates this whole system is time-to-first-meaningful-PR. If you don't establish a baseline before the agent ships, you have no way to claim improvement. The measurement cost is a spreadsheet and a conversation with engineering managers about what 'meaningful' means. Do it before you write the first line of agent code.

The bottleneck is not access to code. It is access to context. Every engineering organization sits on months of accumulated decisions, tradeoffs, and operational scars embedded in artifacts nobody curates for onboarding. The agent does not write new docs. It indexes the artifacts that already exist and makes them retrievable on the day someone new needs them.

Ship Layer 1 first. Repository access only — minimal integration cost, immediate signal. Add Layer 2 once the service briefs are accurate enough that engineers stop correcting them. Add Layer 3 last, after sprint integration and skill profile intake are stable. The system compounds: every new hire who uses it sharpens the index for the next one.^[2]

Tribal knowledge is a single point of failure. Index it before the next hire shows up.