Engineering Handoff Checklist: When a Developer Leaves the Team

When an engineer gives notice, the clock starts on everything that lives only in their head. Which cron job they restart by hand once a month. Why the payments retry logic has that odd exponential cap. Which vendor contact actually answers emails. The credentials they set up for an integration that nobody else knows exists. Most teams handle this with a few hand-wavy "knowledge transfer" meetings in the last week and then discover the gaps one incident at a time over the following year.

A good handoff is not more meetings. It is a structured inventory, built mostly from data, followed by a transfer where the receiving person actually does the work while the departing person is still around to answer questions. This guide gives a timeline, a checklist and the commands to build the inventory. It works whether you have four weeks' notice or one.

Key takeaways

• Start the inventory on day one of the notice period. Build it from data (git, CODEOWNERS, on-call, tickets, cloud consoles), then fill gaps with an interview.
• Every item in the inventory gets a named new owner. "The team" is not an owner.
• Transfer by doing: the new owner performs each recurring task and ships a change in each area while the departing engineer watches.
• Capture the "why" in the code and in ADRs, not in a handoff document that nobody will find later.
• Rotate access and credentials the departing engineer created, and verify nothing breaks when their accounts are disabled.
• Schedule a 30-day follow-up after departure to catch what was missed.

The timeline

When	What happens
Day 1 to 3	Build the inventory from data. Interview the departing engineer to fill gaps. Assign new owners.
Week 1 to 2	Paired work. New owners shadow, then lead, recurring tasks and changes in each area.
Week 2 to 3	Write down what is still undocumented. Record walkthroughs. Rotate credentials.
Last week	New owners work independently, departing engineer reviews. Final open-work handover.
Departure + 30 days	Retrospective on what was missed.

With one week's notice, compress it: inventory on day one, paired work on the highest-risk items only, and record a walkthrough of everything else.

Step 1: Build the inventory from data

Memory is unreliable here, in both directions. The departing engineer will forget things they do routinely, and overemphasize recent projects. Start from systems.

Code they own

# Directories where they authored commits in the last 18 months
git log --author="alex@company.com" --since="18 months ago" --no-merges --format= --name-only \
  | grep -v '^$' | cut -d/ -f1-3 | sort | uniq -c | sort -rn | head -40

Then find where they are the dominant or only recent contributor, because those areas are the real risk:

for d in services/billing services/notifications infra/terraform; do
  echo "== $d"
  git shortlog -sne --no-merges --since="18 months ago" -- "$d" | head -5
done

Check CODEOWNERS for their username, and search for them as a named reviewer:

git grep -n "@alex" -- .github/CODEOWNERS

The method is the same one described in knowledge silos and bus factor; the difference is urgency.

Systems and operations

• On-call schedules and escalation policies that include them.
• Alerts and dashboards they created, especially those routed to them personally.
• Cron jobs, scheduled pipelines and scheduled cloud functions they set up. Search infrastructure code and CI config for their name in comments, and check the scheduler's UI.
• Runbooks they wrote or are the only one to have executed.
• Any manual recurring tasks: certificate renewals, data fixes, report exports, quarterly cleanups.

Accounts, credentials and vendors

• Service accounts, API keys and deploy keys they created. Check your secrets manager's audit log for items they created.
• Third-party services where they are the account owner or billing contact.
• Vendor relationships where they are the technical contact.
• Personal access tokens used by automation. These break the day the account is disabled.

Open work

• Open PRs and branches. gh pr list --author alex --state open and git branch -r --sort=-committerdate | head -30 then filter.
• Tickets assigned to them, and tickets where they are the only one with context in the comments.
• Promises made to other teams that are not in any ticket.

Step 2: Interview to fill gaps

Spend an hour with the departing engineer going through the data-driven list, then ask the questions data cannot answer.

• What do you do regularly that is not written down anywhere?
• What breaks, and how do you usually fix it?
• Which part of your code are you least proud of, and why is it like that?
• What decisions did you make that someone might want to undo, and what would go wrong if they did?
• Who outside the team depends on you, and for what?
• What are you worried will happen after you leave?

The last question is often the most useful. People know where the bodies are buried.

Step 3: Assign new owners

Every row in the inventory gets exactly one new owner, and ideally a backup. Write it down as a table and share it with the team and with anyone outside who depends on these systems.

Item	Type	Risk	New owner	Backup	Transfer method
services/billing/reconciliation	Code	High	Priya	Sam	Paired ticket, recorded tour
Monthly ledger export job	Ops	High	Priya	Dmitri	Shadow, then run it solo
Payment processor webhook config	Vendor	Medium	Sam	Priya	Walkthrough, update contact
infra/terraform/queues	Code	Medium	Dmitri	Sam	Review next two changes
Payment sandbox API key in CI	Credential	Medium	Dmitri		Rotate to service account

Update CODEOWNERS and on-call schedules in the same week, not after departure. Changing them early forces the new owners to engage while help is still available.

Step 4: Transfer by doing

Explanations fade within days. Doing sticks. For each high-risk item:

1. Watch. The departing engineer performs the task or walks through the code while the new owner takes notes.
2. Do with help. The new owner performs it, or ships a real change in the area, with the departing engineer pairing but not driving.
3. Do alone. The new owner does it independently, and the departing engineer reviews afterward.

For code areas, pick a real ticket from the backlog for step 2 and step 3. A small bug fix in the reconciliation job teaches more about it than an hour-long overview. For recurring operational tasks that happen monthly or less, do a dry run now rather than waiting for the real one.

Step 5: Capture the context that will not transfer by doing

Some knowledge will not come up during paired work: past incidents, rejected alternatives, the reasons for odd constraints. Capture it where future readers will look.

• In the code. Comments explaining non-obvious decisions, linked to tickets or incidents.
• In ADRs. For significant design decisions, write a short record of the context, the decision and the consequences. The ADR guide has a template.
• In runbooks. One per recurring or failure-prone operation: when to run it, the exact commands, how to verify it worked, and what to do if it fails.
• In a recorded walkthrough. For each major area, a short recorded tour of how it fits together, with the outline and file links saved next to the code. See how to run a codebase walkthrough.

A runbook template that stays useful:

# Monthly ledger export

When: first business day of the month, before 10:00 UTC
Owner: @priya (backup @dmitri)

## Steps
1. Confirm the previous day's reconciliation job succeeded (dashboard link).
2. Run: `make ledger-export MONTH=2026-10`
3. Verify: row count in the export matches `SELECT count(*) FROM ledger_entries WHERE ...`
4. Upload to the finance bucket and post the link in #finance-ops.

## If it fails
- Timeout: rerun with `BATCH_SIZE=5000`.
- Mismatched counts: do not upload. Page the billing owner.

## History
- 2026-03: export moved from cron to the scheduler after the host was retired.

Step 6: Access and credentials

Before the last day:

• Move every credential the departing engineer created to a service account or a team-owned secret, and rotate it.
• Replace personal access tokens in CI and automation with app tokens or service accounts.
• Transfer ownership of third-party accounts and update vendor contacts.
• Remove them from on-call and from alert routing.

On the last day, disable their accounts on schedule and watch dashboards and CI for the next day or two. If something breaks, you found a dependency the inventory missed. That is much better than finding it during an incident a month later.

Step 7: Hand over open work

For each open PR or in-progress ticket, decide one of three outcomes: finish it before departure, hand it over with a written status, or close it. A handover status should say what is done, what is left, what was tried and did not work, and where the branch is. Close anything nobody will pick up rather than leaving it to rot.

Step 8: Follow up after 30 days

A month after departure, the new owners and their manager spend half an hour on three questions. What came up that was not in the inventory? Which items felt shaky? What should we change in the checklist for next time? Fold the answers into the checklist so the next handoff is better.

Making the code easier to inherit

The hardest part of inheriting someone's code is building a mental model of it fast enough to be useful before they leave. A generated map shortens that. OpenVisio indexes a repository in the browser, so a new owner can open Explore to see how the inherited modules connect to the rest of the system, and ask targeted questions in Ask to get explanations anchored in the actual source before a pairing session. The paired work and the written context still matter most; the map helps the new owner arrive at those sessions with better questions.

A handoff done well is mostly invisible afterward. Nothing breaks, nobody has to message a former colleague, and the new owners make their first independent changes without drama. That outcome comes from an inventory built from data, a named owner for every item, and transfer by doing.