Building around codebase onboarding for small product teams - feedback wanted
Hey IH,
I'm a founder working on an existing product with a small team, and one problem keeps showing up.
Adding another developer does not automatically make the team faster.
Repo setup is not the issue. Writing the first small PR is usually not the issue either.
The harder part is getting someone new to understand enough of the product and codebase to make a real change without pulling the founder, CTO, or senior engineer into every decision.
Things like:
• which screens, APIs, services, core business objects, and modules are tied together
• which product flow a change belongs to before someone starts editing code
• which services or modules usually need senior review before a PR moves forward
• which areas have weak tests or low confidence and need extra care
• what should not be changed right before a release
• which old product or technical decisions only live in someone's head
I'm exploring a product around this gap.
The core idea is to help small product teams carry codebase structure, product-flow context, senior-review concerns, and release-sensitive notes with the work, so adding contributors creates speed instead of more re-explaining and cleanup.
Current stage: validation / early product direction.
I'd love your perspective:
• Have you hit this when adding devs, contractors, or a co-founder to an existing product?
• What are you using today: docs, diagrams, pairing, PR notes, code walkthroughs, Slack, issue boards, or tribal knowledge?
• What would make this painful enough to pay for?
• What would make you skeptical of a tool in this space?
My goal is to understand whether this is a real problem for small product teams, or just something that feels painful because I'm close to it.
This problem has a structural counterpart in extension/SaaS launch work, which is the angle I'm coming from. Substitute "Chrome Web Store reviewer" for "new contributor" and your list reads almost identically: the reviewer also has the codebase, also has the manifest/PR, and the gap is exactly the implicit product/decision context that lives in someone's head — why this permission is here, which scope expansion is intentional vs accidental, what's a structural constraint vs a fixable mistake. Same shape of problem, different audience.
Two patterns from that domain that might transfer:
The thing that actually moves the needle isn't a generated doc — it's a generated doc keyed on the artifact the new contributor is touching. Generic onboarding docs ("here's our architecture") get skipped because they're not about the current PR. The version that gets read is "for the file/module you just opened, here are the 3 implicit decisions and the 1 person who'd care if you broke them." Surface is per-artifact, not per-codebase.
Second: explicit TODO markers in generated docs beat polished prose. Once you start auto-generating context, the generator will impute things it can't actually verify ("this module probably handles X"). Marking those uncertainties inline ("TODO: confirm with @senior whether this assumption still holds") forces the human in the loop to do the one thing only they can do, and stops the doc from quietly becoming wrong as the codebase drifts.
The hardest version of your problem is probably the last bullet — decisions that only live in someone's head. Even the best static analysis can't extract those; you'd need a lightweight capture loop at the moment the senior is making the decision (commit message convention, PR description template, something). Otherwise you're competing with their memory and losing.
What does your current prototype look like — static-analysis-driven, or are you capturing live developer context somehow? That's the design fork I'd be most curious about.
The per-artifact point makes sense. A big architecture doc is easy to ignore. Context tied to the file, module, or PR someone is touching feels closer to the right shape. I also agree on explicit unknowns. For the prototype, repo analysis during onboarding is the base, with rescans as the codebase changes so the map doesn’t freeze. The part I’m working through is how to tie that map to PR/review context without creating another doc chore. Where would you expect that to be least painful to capture: PR comments, review notes, commit/branch notes, or somewhere else?
Capture surface is the question I'd anchor on first. Three sub-surfaces I'd rank by friction-to-real-signal ratio:
PR comments are the highest fidelity but also the highest opt-in cost — the dev has to remember to invoke them. Where I've seen this work without becoming a chore is keeping the capture machine-readable: a structured comment template (
/context: this PR depends on X assumption, will break if Y changes) that your tool harvests rather than free prose. Reviewers ignore prose, but they'll fill a single-line annotation if the cost is one extra line.Commit/branch notes are interesting but lossy — they're scoped to a moment, not a decision. The framing I'd try here is "what would have to be true for this to be safe to merge?" captured at commit time, not after. This is closer to a test-style assertion than a doc, which is psychologically different (devs don't resist assertions, they resist documentation).
The third surface, which doesn't appear on your list, is review-time conversation — the back-and-forth in PR review that contains the actual implicit reasoning, before it gets compressed into the merged commit. That stuff dies the moment the PR closes. If your tool could harvest review comment threads and attach them to the affected files (not the PR), you'd capture the senior-review reasoning without asking anyone to write a separate doc. The cost is post-hoc, not in-the-flow.
The pattern I've found useful in adjacent territory: don't ask the dev to document, ask the dev to annotate something they were already going to write. Annotations on a thing have ~5x adoption vs. documentation about a thing, because the annotation is colocated with the work and decays naturally with the code.
On the rescan-during-onboarding-and-on-changes design: that part is sound. The thing I'd watch is what happens when the rescan disagrees with a previously-captured human annotation. Your tool can't tell which is right; the dev probably forgot they wrote it. Surfacing "this annotation was added when X module had Y shape — module now has Y' shape, please reconfirm" turns that conflict into a maintenance signal instead of stale doc rot.
Circling back here. I’m still trying to talk to a few people who have seen this in real teams, especially where context starts in docs or diagrams but gets lost once the work moves through tickets, PRs, and review.
If you’re open to a 15-minute chat this week or next, I’d value your perspective. You can reach me at [[email protected]].
Thanks, this is useful. Your point about review-time conversation is probably the key part for me. A lot of the useful context seems to appear during review, then disappears into comments once the PR is merged.
In your experience, is that something you saw once in a while, or did it keep showing up as the product moved toward release?
man, 'technical decisions that only live in someone's head' is the real killer here. repo setup or reading standard api docs is never the issue when onboarding a new contractor or dev.the pain always starts when they make a change in a seemingly isolated module, and it unexpectedly breaks a completely different screen because of a weird data-dependency choice someone made two years ago and forgot to document. right now we just rely on messy code walkthroughs and frantic slack pings right before a release.
if a tool can automatically flag a pr when it touches an area with historically weak test coverage or low confidence without me having to manually leave a github review comment every time, i'd seriously consider paying for it. validation is 100% real.
This is very close to what I’m trying to validate. The example of one module breaking another screen because of an old dependency choice is exactly the kind of thing I’m trying to catch earlier. The direction I’m exploring is a PR-adjacent layer that flags affected areas, weak test coverage, low-confidence modules, and reviewer context before someone has to manually catch it. In your case, would this help most before the dev starts, when the PR opens, or during review?
honestly, right when the PR opens is the sweet spot for me.
before the dev starts coding is too early because half the time we don't even know what exact database or module paths we'll end up modifying until we're deep in the refactor. and during manual review is too late because by then the founder or cto is already pulled into the context switch and reading the diff anyway.
if a bot can just drop an automated comment the second a pr is opened—saying something like 'hey this touches a low-confidence legacy service, make sure to manually double check the billing screen data dependencies'—that's a lifesaver. it prevents the review fatigue entirely.
Thank you Eva, The timing point is clear. That makes sense because the reviewer is already in the flow, but the team has not yet burned time chasing the wrong areas. In your experience, does this kind of PR-time warning matter on most changes, or mainly on refactors / fragile areas / release-sensitive work?
This is a real problem, especially for small teams where the senior context is not documented because everyone is moving too fast.
The painful part is not onboarding itself. It is that every meaningful change requires hidden product judgment: which flows are connected, which modules are fragile, which decisions are historical, and where a new contributor should not touch without review.
That makes this more interesting than documentation. It feels closer to a codebase judgment layer for small teams.
I’d be careful not to frame it too broadly as “developer onboarding,” because that can sound like docs, checklists, or repo setup. The stronger wedge is helping new contributors avoid expensive wrong changes before the PR even starts.
If you build around that, a harder technical brand like Davoq .com would fit better than a soft productivity-style name. The product is about trust, codebase risk, review boundaries, and product-flow context. That needs to feel serious from the first read.
This is a good correction. I agree the stronger wedge is not generic onboarding. It’s helping a small team avoid expensive wrong changes before the PR starts. ‘Codebase judgment layer’ is closer to what I’m exploring than docs or setup. Would you expect that to show up mainly before coding, inside the PR, or both?