On this page
- How long does developer onboarding take?
- Why onboarding stalls
- What repowise generates for a new hire
- A day-by-day onboarding plan
- Setup: index the repository once
- Day 1: get the map
- Days 2 to 3: understand the assigned area
- Days 3 to 4: learn why before changing it
- Week 1: check the change before the first pull request
- Ongoing: ask instead of interrupting
- How to measure onboarding
- Pitfalls
- FAQ
To cut developer onboarding time, replace hand-written onboarding documentation with documentation generated from the repository: an overview wiki, an architecture map, file ownership, risk hotspots and the recorded reasons behind design choices. Run repowise init --yes --no-prose once and a new engineer has all of it, current to the latest commit, without anyone writing a page. The rest of this guide covers why onboarding stalls and a day-by-day plan you can follow. It is one spoke of the wider playbook on how to onboard engineers faster on any codebase.
How long does developer onboarding take?
The most widely used measure is time to the 10th merged pull request, and DX found it averaged 91 days for developers who did not use AI daily and 49 days for those who did. That comes from a random sample of 400 companies between October 2025 and February 2026, as DX reported. DX's April 2026 average across the sample was 33 days.
The metric matters because early pace predicts later pace. Microsoft researcher Brian Houck has said that by a developer's 10th pull request there is a better than even chance of predicting their output pattern two years out, a point DX cites. Ramp-up is a trajectory set in the first weeks, not a cost that washes out.
Why onboarding stalls
A new developer is rarely short of skill. They are short of four kinds of context that no README holds.
- A map. Which modules exist, what depends on what, where execution starts.
- Owners. Who knows the billing code, and whether they still touch it.
- Risk. Which files are complex and constantly changing, where a first change is most likely to break something.
- Reasons. Why the code is shaped this way, so the new hire does not undo a deliberate choice.
Hand-written documentation covers these for a week and then drifts. A new developer following an outdated page builds a wrong mental model, which is worse than having no page. Tribal knowledge fills the gap, and it costs senior time on every hire: the same "where is X" questions, answered one Slack thread at a time.
What repowise generates for a new hire
repowise reads the repository, its git history and its decision records and produces each of the four kinds of context from them. Everything below is computed during repowise init and refreshed on repowise update, so it tracks the code.
| New-hire question | What answers it | Where to find it |
|---|---|---|
| Where do I start? | Overview wiki with an onboarding collection: Project Overview, Getting Started, Key Concepts, How It Works | repowise serve, or get_overview |
| How is it laid out? | Architecture map from the dependency graph: modules, layers, entry points | dashboard, get_overview |
| Who do I ask? | Primary owner, recent owner and bus factor per file, from git history | get_context with include=["ownership"] |
| What could I break? | Hotspot and fix-history cues, plus the files that depend on the one you change | get_risk |
| Why is it built this way? | Decision records, with git archaeology as a fallback | get_why |
| How does this work? | A cited answer from the wiki and symbol index | get_answer |
Scroll the table sideways to see every column.
The wiki is mostly rendered from code structure with no model in the loop, so a repository indexed without an API key gets a complete wiki, not a placeholder. Adding a provider key writes prose for the subsystem and overview pages. Details are in the wiki layer docs and on the wiki feature page.

Ownership means who wrote the most commits and lines, computed from git log and git blame. It points a new hire at the right person to ask, which is what they need on day two. See git intelligence for how it is derived.
A day-by-day onboarding plan
Each step below uses one call and answers the question a new hire has at that point. Run them in the dashboard or let the new hire's agent call them over MCP.
Setup: index the repository once
pip install repowise
cd your-repo
repowise init --yes --no-prose # no questions, no API key, no spend
repowise serve # browse the wiki and map at localhost:3000
Run repowise update after commits to re-render only what changed. repowise init registers the MCP server with Claude Code, and repowise mcp starts it for other clients such as Codex and Cursor. The quickstart lists every option.
Day 1: get the map
Ask for the architecture once, at the start. get_overview returns the summary, key modules, entry points, architecture layers, the heaviest package-to-package dependencies, and code and git health.
get_overview()
get_overview(include=["tour", "ownership"]) # guided reading order and top owners
The tour block gives a reading order, which replaces the "read these ten files first" list someone would otherwise maintain by hand.

Days 2 to 3: understand the assigned area
When the first ticket lands, point get_context at the files or module it touches. It returns summaries, symbols with signatures and hotspot and fix-history cues, and with include it adds ownership and decisions. For "how does this work" questions, get_answer returns a cited answer.
get_context(targets=["src/auth/session.py"], include=["ownership", "decisions"])
get_answer(question="How does the authentication flow work?", scope="src/auth/")
The ownership block names the primary owner, the recent owner and the bus factor, so the new hire knows whom to ask and how many people really know the file.
Days 3 to 4: learn why before changing it
Before refactoring or diverging from a pattern, ask get_why. It returns the decision records governing a path. Where none exist, it falls back to git history and rationale comments.
get_why(query="why JWT over sessions?")
get_why(query="src/payments/processor.ts")

A decision record turns "someone told me not to touch that" into a written constraint with the reason attached, which is the part that normally leaves with the person who made it. See how repowise records architectural decisions.
Week 1: check the change before the first pull request
Before opening the pull request, score the change. get_risk takes the changed files and reports hotspot status, owners and the files that depend on them. get_change_risk scores a commit or range.
repowise risk --target src/auth/session.py # owner, recent owner, bus factor
get_risk(changed_files=["src/api/routes.ts", "src/middleware/cors.ts"])
A high result tells the new hire to run the tests that matter and to request review from the named owners. That is the safe way to make a first contribution.
Ongoing: ask instead of interrupting
search_codebase finds an identifier or a concept by hybrid search, and get_answer handles the how, where and why questions that would otherwise go to a senior. Both work from the index, so the answer reflects the current code. See the MCP tools reference for all ten default tools, and a live example on FastAPI to try the wiki without installing anything.
How to measure onboarding
Track time to 10th merged pull request, the metric DX and Microsoft use, and pair it with two signals you already have. Measure each cohort against the one before it.
| Metric | How to read it |
|---|---|
| Days to 10th merged pull request | Start date to the 10th merged PR. DX's April 2026 sample averages 33 days |
| Review rounds on first pull requests | Fewer rounds of pattern and convention comments means the new hire found the right context |
| Questions routed to senior engineers | Count "where is X" threads per new hire; self-serve answers should shrink it |
Scroll the table sideways to see every column.
Change one thing at a time. If you introduce the wiki and the MCP server together, you cannot tell which moved the number, so start with the generated wiki and map, then add agent access.
Pitfalls
- Treating generated docs as a replacement for a person. The wiki and map answer "where" and "what". A buddy or mentor still answers "how do we work here". Use the generated material to make that conversation about judgment instead of directions.
- Indexing a shallow clone. Ownership and bus factor describe only the commits fetched. Run
git fetch --unshallowbeforerepowise initfor the full history. - Reading ownership as responsibility. An owner here is the person with the most commits and lines. Confirm who is accountable before assigning review.
- Skipping the refresh. Run
repowise updatein CI or on a schedule so the wiki a new hire reads matches the code they check out.
FAQ
- How long should developer onboarding take?
- There is no single target, but time to the 10th merged pull request is the common benchmark. DX measured an average of 33 days in April 2026 across a sample of companies, and 49 days versus 91 days for daily AI users versus non-users in Q4 2025. Measure your own cohorts against that.
- What should developer onboarding documentation include?
- Four things: a map of the modules and entry points, who owns each area, which files are risky to change, and the reasons behind key design choices. Setup steps and team norms still belong in a short hand-written page. The first four can be generated from the repository so they never go stale.
- Does repowise need an LLM API key to generate onboarding docs?
- No.
repowise init --yes --no-prosebuilds the wiki, architecture map, ownership and risk data keyless, with no model calls and no spend. A provider key adds model-written prose to the subsystem and overview pages. - Can a new hire use this with Claude Code or Cursor?
- Yes.
repowise initregisters the MCP server with Claude Code, andrepowise mcpserves it to Codex, Cursor, Cline and other MCP clients. The agent then calls tools likeget_overview,get_contextandget_answeragainst the index instead of guessing. - Does it work on a private repository?
- Yes. repowise is open source under AGPL-3.0 and runs locally, so the index stays on the machine. The hosted app offers two public repositories on the Free plan, and private repositories on Pro.
- How many languages does repowise support?
- 28 languages are parsed to a full syntax tree, and 15 of them reach the Full tier. See the language support layer for the matrix.



