Access is sorted and the laptop works, but the new engineer still asks a senior teammate forty questions a day. Automated engineer onboarding with a mentor agent answers the “why is it like this?” questions from your own repos, ADRs, and incident history, with citations, and logs every gap it finds.
Most teams have fixed the paperwork half of onboarding. Accounts get provisioned, the laptop image is standard, the first PR is a docs typo. Then the real cost shows up: the new engineer spends week two through week six interrupting whoever sits closest with questions that only live in people’s heads. Why does the checkout service have two retry layers? Which of the three Terraform modules is the real one? What happened in the March incident that everyone references but nobody wrote down?
Every one of those questions costs two people’s attention: the person asking and the senior engineer who stops what they were doing to answer. Multiply by forty a day and you have the hidden tax of onboarding. Automated engineer onboarding, in the sense we mean here, is a mentor agent that answers those questions from the sources the team already has, cites where it found the answer, admits when it cannot, and turns every “nobody wrote this down” into a documentation ticket.
See the pattern in action, tap through the tabs below:
[2026-09-06 onboarding] the interruption tax
Week one is solved by provisioning. Weeks two through six are where ramp time actually goes: the new hire has access to everything and understands none of it, and the only search engine for “why” is a senior engineer’s memory.
Typical numbers from teams we work with: 30 to 50 context questions a day in the first month, each one costing 5 to 15 minutes of a senior engineer’s focus. That is a second full-time salary spent on answering questions the team already answered once, in a PR comment or a postmortem, and then forgot.
Goal: a first answer in under 30 seconds with a citation, a human escalation only for the questions that truly have no written answer, and a growing list of doc gaps the team can actually fix.
[2026-09-06 onboarding] mentor-agent.yaml
# Knowledge-grounded mentor agent for new platform engineers
name: platform-mentor
surface: slack # DM the bot, or @mention it in #platform-newbies
team: platform-eng
knowledge_sources:
- kind: git
repos: [infra-terraform, checkout-api, platform-runbooks]
include: ["**/*.md", "**/*.tf", "**/*.go", "**/*.py"]
history: pr_descriptions_and_review_comments # the "why" lives here
- kind: adr
path: docs/adr/ # architecture decision records, newest wins
- kind: postmortems
path: incidents/ # every "remember March?" story
- kind: slack_export
channels: ["#platform-eng"]
since_days: 365
answer_policy:
cite_or_decline: true # no citation, no confident answer
max_sources: 4
prefer_newest_when_conflicting: true
flag_conflicts: true # "ADR-14 says X, but PR 2211 changed it"
escalation:
when: [no_source_found, confidence_below_0.6, question_is_about_access_or_secrets]
route_to: "@platform-buddy" # rotates weekly
include_context: true
gap_tracking:
on_escalation: create_issue
repo: platform-runbooks
label: docs-gap
dedupe_similar: true
guardrails:
read_only: true
never_surface: [secrets, personal_data, hr_channels]
[2026-09-06 onboarding] DM with platform-mentor, simulated
09:14 [dana] why are there two retry layers in checkout-api? client AND gateway?
09:14 [mentor] Short version: the gateway retry came first, the client retry was added
during the March 12 incident when the gateway's retries amplified a
payments outage (retry storm). The client retry has a circuit breaker;
the gateway one does not.
Sources: incidents/2026-03-12-payments-storm.md (sec 4)
PR 2211 "add client-side breaker" (review thread)
ADR-14 "retry strategy" (partially outdated, see note)
Note: ADR-14 still says "gateway retries only". PR 2211 changed that
and ADR-14 was never updated. Flagging as docs-gap #318.
09:16 [dana] which terraform module is the real vpc one? there are three
09:16 [mentor] modules/vpc is current. modules/vpc-legacy and modules/network are
both deprecated per PR 1874 (Jan) but not deleted.
Sources: infra-terraform PR 1874 description
#platform-eng, 2026-01-22 thread (Marcus)
09:31 [dana] how do I get write access to the prod kubeconfig?
09:31 [mentor] That's an access question, so I won't answer it directly.
Escalating to @platform-buddy (this week: Priya) with your question.
09:38 [priya] hey dana, prod write is by request through the access portal, I'll
walk you through it at 10.
17:00 [mentor] Daily summary for #platform-eng:
12 questions answered with citations, 2 escalated, 1 docs-gap opened.
Top unanswered theme this week: "why is X deprecated?" (4 asks).
[2026-09-06 onboarding] start here checklist
1. Index the “why,” not just the “what.” PR descriptions, review comments, ADRs, and postmortems are the sources that answer onboarding questions. The code itself rarely explains itself.
2. Make citation mandatory. An answer without a source link is a guess. Configure the agent to decline rather than guess.
3. Route access and secrets questions to a human, always. The agent should recognize them and hand off, never answer.
4. Turn escalations into doc tickets automatically. That is how the knowledge base gets better every week without a “docs day.”
5. Post a daily summary. Questions answered, escalated, gaps opened. The senior engineers see the interruption tax drop in numbers.
Why provisioning bots do not fix ramp time
Access automation solves day one. It does nothing for the month that follows, because the bottleneck is no longer permissions, it is context. A new engineer with full access to twelve repos and a 400-page wiki is not onboarded. They are lost with credentials.
The context they need does exist. It is scattered across pull request descriptions, code review threads, architecture decision records, postmortems, and a year of Slack. No human can search all of that quickly, so the new hire asks a person, and the person answers from memory, and the answer is never written down. The mentor agent's job is to be the search engine for "why," and to make the team's written record better every time it fails to find an answer.
How it's built
The pattern is retrieval-grounded question answering with a strict citation policy, a human escalation path, and a feedback loop into documentation. Three pieces.
The knowledge layer
Index the sources listed in the YAML above. The two that matter most, and that most teams forget, are PR descriptions with their review comments and postmortems. That is where decisions get explained. Git history plus a docs folder is a good start; adding a filtered Slack export of the team's engineering channel is what makes the agent feel like it has actually been on the team for a year. Chunk by document section, keep the file path and commit or PR number as metadata, and re-index nightly.
The mentor agent
A single tool-calling agent with four tools: search_knowledge(query), read_source(path_or_pr), escalate(question, context), and open_docs_gap(summary, sources_checked). The system prompt enforces three rules: cite or decline, flag conflicts between sources rather than silently picking one, and never answer questions about access, secrets, or people. The conflict rule is underrated. "ADR-14 says X but PR 2211 changed it" is exactly the kind of answer a good senior engineer gives and a naive chatbot never does.
Model choice is not the hard part. A mid-tier hosted model works well; so does a local 7B-class open model through Ollama if your repos cannot leave the building, and this week's fully open K2 Horizon release (see the roundup) makes that option stronger than it was a month ago.
The feedback loop
Every escalation opens a deduplicated docs-gap issue with the question and the sources the agent already checked. Every Friday the team spends 20 minutes closing the top three gaps by writing the missing ADR or runbook section. That is the whole documentation strategy, and it works because it is driven by real questions instead of good intentions. The daily summary in the team channel keeps the interruption tax visible and shrinking.
Wiring options
A Slack Bolt app plus a small LangGraph or CrewAI graph covers the agent side in a few hundred lines. If your team lives in n8n, the same thing is a webhook trigger, a vector search node, a model node, and two branches for escalate versus answer. The YAML policy file is the product; the framework is a detail.
Three ways this goes wrong
Indexing only the wiki. The wiki is where stale knowledge goes to look authoritative. Index decisions, not summaries.
Letting the agent guess. One confident wrong answer about a production system erases a month of trust. Cite or decline, no exceptions.
Skipping the gap loop. Without the docs-gap tickets, the agent plateaus at whatever your documentation covered on day one. With them, it gets better every week, and so does your team's written memory.
What good looks like after 30 days
- Senior engineers report fewer than 10 onboarding interruptions a day, down from 30 to 50.
- The new hire's first non-trivial PR lands in week two instead of week five.
- Twenty-plus docs-gap issues opened and at least half closed with real ADRs or runbook sections.
- Zero access or secrets questions answered by the bot, every one escalated with context.
If you would rather have this mentor workflow designed and stood up for your team, our DevOps Boot Camp covers knowledge-grounded agents end to end, and the wider course catalog has the security track for the guardrail side. No pressure, the checklist above is enough to start on your own.
FAQ
What is a mentor agent for engineer onboarding?
It is a chat-based AI agent grounded in your team's repos, ADRs, postmortems, and engineering channel history. It answers a new hire's "why is it like this?" questions with citations, escalates to a human buddy when it cannot find an answer, and opens documentation tickets for every gap it hits.
How is this different from pointing a chatbot at the wiki?
Two things: the sources and the policy. It indexes decisions (PR descriptions, review threads, incident reports) rather than summaries, and it is required to cite a source or decline, and to flag when sources conflict, instead of producing a fluent guess.
Is it safe to give an AI agent access to all our repos?
Give it read-only access, exclude secrets and HR or personal channels at index time, and hard-route any access or credentials question to a human. With those three controls, the agent sees nothing a new engineer could not already read.
