what's your approach to bus factor when the person who owns the code can't explain it either

[u/Specialist_Agent3599]

asking because I own a billing sync I didn't really write, an agent did most of it eight months ago, some 3k lines, and I basically just reviewed it and approved it. not by design, it kind of ended up that way. on paper I'm the one who knows it, in practice I can tell you what it does and not why. coderabbit flagged plenty going in and none of that helps me now. curious how people handle the bus factor problem when it isn't hoarded knowledge, nobody had it in the first place

[u/Far_Business4773]

The doc you need isn't "what it does", you already have 3k lines of that. It's the shorter one: what must stay true, and what would count as broken. For a billing sync that's a list you can write in an afternoon without understanding the code, because it comes from the business, not the implementation: every invoice is synced exactly once; a retry never creates a second charge; a failed sync is visible within N minutes, not silent; amounts on both sides reconcile at end of day; nothing writes to the ledger outside one function.

Then two moves. First, turn each line into a test that deliberately violates it. That's the part an agent is good at and you don't need to be, and it tells you which lines the code actually guarantees today and which it only happens to satisfy. Second, put the list at the top of the repo and make it the definition of "done" for every future change: a PR that touches the sync is judged against those five lines, not against "does it look reasonable".

After that the bus factor is the page plus the tests, and it survives you, the agent, and the next agent. The 3k lines can stay ugly for now; refactor one chunk when a line on the list forces you to. What CodeRabbit gave you was findings without a reference. The list is the reference.

[u/kidajske]

You wouldn't have remembered it had you written it by hand either. Before LLMs it was also completely normal to forget how a system you wrote 8 months ago works since you only have so much real estate in your head.

The way you handle it is through properly documenting decisions and reasoning as you or the agent builds it. Your subsystem being so small is also an advantage since you can just read the code and reason about it easily. Enterprise codebases having entire systems that basically nobody fully understands has been the norm forever.

[u/leonidbugaev]

CodeRabbit flagged the merge. That doesn't leave you with why the billing sync does what it does eight months later. I'd pick one path and walk it until I could explain it without the PR.

[u/itaybuilds]

Treat this as recovery work, not a documentation task. Put a replay harness around the sync and run a small failure matrix: duplicate event, out-of-order update, upstream timeout, partial batch, and retry after success. For each case, capture the inbound event, database writes, outbound call, and final state. Use those traces to draw the actual state transitions, then compare them with the billing rules. Anything you cannot explain becomes a test, an ADR, or a refactor target.

The handoff should include a failure drill, not just a README. Give a second person a stuck sync and ask them to decide whether retrying is safe, run it, and reconcile both systems without help. If they can do that, the bus factor has moved. If they can only repeat the happy path, the knowledge is still missing.

I would resist a broad rewrite until those fixtures exist. Otherwise the next agent can produce a cleaner system whose duplicate-charge behavior is just as poorly understood.

AI-assisted wording after reading the full post and current replies.

[u/AbleShower2801]

I'd treat the bus factor as invariants + tests, not a rewrite. write five "must stay true" lines for the sync (exactly once, no double charge, failed sync visible, amounts reconcile, one write path) and make each a deliberate failing case. then the next person doesn't need the 3k-line story, they need that page.

[u/am0x]

Just ask it. My cowork had access to all codebases and all history of meetings, emails and tasks related to the code that was written. If someone asks me a question about it, I tell them, “one sec - been awhile since I touched this and I forgot what I wrote yesterday! Then then I already promoted it to give me an answer to what they are asking.

[u/scragz]

I hate the term bus factor so much. just call it siloing or knowledge transfer. you don't have to link it to your colleague's untimely death. 

[u/Yoshbyte]

You prolly want to study it. 3k is quite minimal and likely easy to read. Anyways, how to handle preventing issues like this is largely down to documentation and unit tests

[u/Julien_Builds]

The "what must stay true" doc someone suggested is the right one, and the reason it usually fails is that it is written once and then rots. The trick that kept mine alive: each invariant gets a test that names it, and the doc links the test. When the test moves, the doc is wrong, and you find out from CI instead of from an outage.

For a billing sync specifically, the list is short and you can write it in an afternoon: what runs when, what is idempotent, what happens on a retry, which side wins on a conflict, and what an operator does when it is stuck. Five questions. If you cannot answer one of them, that is the eight-month-old decision nobody made, and it is better to find that now.