Inheriting a Codebase You Did Not Write: The First Two Weeks
The instinct on day 1 of a handover is to open the worst file and start fixing. Resist it. For 2 weeks the job is to make the system observable and stoppable, not better.
The situation arrives in 2 shapes. An acquisition closes and the acquired product is now yours, or a vendor's last day is Friday and the knowledge transfer was a 90-minute call plus a README last edited 14 months ago.
Both shapes produce the same trap. There is enormous pressure to demonstrate value in week 1, and the fastest visible action is to change something. Changing something before you can measure or reverse it is how a handover turns into an incident.
What follows is the sequence we run. Destm has taken over systems across 200+ projects since 2013, and the order below has held up more consistently than any framework preference we have.
Days 1 to 3: what to read, and deliberately not the code
- The deploy pipeline. How does a change reach production, who is allowed to push, and is there a rollback? If nobody can answer within 2 hours, that is finding number 1 and it outranks everything else.
- The runtime topology. What is actually running, on what, in which account or cluster. Compare against the diagram you were handed and assume the diagram is 18 months stale.
- The data model. Schemas, migration history, and which tables carry foreign keys. Foreign-key coverage is the fastest proxy for how much integrity lives in the database versus in application code you have not read yet.
- The integration surface. Every outbound credential, every inbound webhook, every scheduled job. Undocumented business logic hides in cron more reliably than anywhere else.
- Only then the application code, entered through the highest-churn files rather than through the entry point.
Reading in this order answers a different question than reading the code does. It tells you what the system can do to the business while you are still learning, which is the risk you are being paid to hold.
What the git history says that the code does not
Version history is the cheapest domain expert available in week 1, and it does not require anyone to be still employed.
# bus factor: who actually built this, and are they gone?
git log --format='%an' | sort | uniq -c | sort -rn | head -15
# churn: where does the business keep changing its mind?
git log --format=format: --name-only --since=12.month \
| sed '/^$/d' | sort | uniq -c | sort -rn | head -40
# archaeology: when did this flag or constant first appear?
git log -S'LEGACY_TAX_MODE' --oneline
# regressions that predate you, found without understanding the code
git bisect start
git bisect bad HEAD
git bisect good v4.2.0
git bisect run ./scripts/repro.sh
The churn list is the most valuable output. High-churn files are where the business rules genuinely live, where your first production bug will originate, and where any test-writing budget should go first.
git bisect deserves special mention for handovers because it finds the offending commit by binary search over history, without requiring you to understand the code. On a 675-commit range that is roughly 10 test cycles.
If one author accounts for 70% of commits and has left, your risk is knowledge rather than code quality. That distinction changes the plan: you need documentation and tests, not a refactor.
Measure before you touch anything
You cannot claim an improvement without a before, and you will be asked for one. Capture these in week 1 while nobody expects you to have changed anything yet.
| Baseline | Where it comes from | Why it matters this early |
|---|---|---|
| Deployment frequency and change lead time | CI history, tags, merge timestamps | Sets the ceiling on how fast you can fix anything |
| Change fail rate and recovery time | Incident log, rollback and hotfix commits | Tells you whether you can safely move at all |
| p75 latency on the top 5 endpoints | Traces if instrumented, access logs if not | The before-number for every later claim |
| Error rate and top 10 exception classes | Log aggregation | The known-broken list the previous team lived with |
| Dependency vulnerability count | Software composition analysis | Sizes the security backlog before anyone promises a date |
| Software bill of materials | SBOM generation | What is in the build, versus what the manifest claims |
| Supply-chain hygiene score | Automated repository checks | Branch protection, pinned dependencies, review requirements |
DORA now publishes 5 delivery metrics rather than the original 4: change lead time, deployment frequency and failed deployment recovery time on the throughput side, change fail rate and deployment rework rate on the instability side. Rework rate is the one that catches handover pain, because it counts the fixes that follow a deploy.
For the security baselines, OWASP Dependency-Check maps dependencies to known CVE entries, CycloneDX produces the SBOM in a standardized format, and OpenSSF Scorecard scores a repository against automated checks covering branch protection, code review, pinned dependencies and workflow token permissions.
If the codebase has no tracing, add it before you add features. OpenTelemetry traces and spans give you the request path through a system whose internal structure you do not yet know, which is the fastest way to learn it.
The handover items that are not code
Three things regularly outrank the codebase in week-1 risk, and none of them appear in a repository.
Licenses and contracts come first. Commercial libraries, managed services and data feeds often carry seat counts or entity names tied to the outgoing owner, and a license that does not transfer becomes a production outage on renewal day.
Data residency and retention come second. Find out which stores hold personal data, where those stores physically sit, and what the stated retention period is, because inheriting a system means inheriting its obligations on day 1.
Third-party account ownership comes last and hurts most. Payment gateway, DNS, certificate authority, error tracker and cloud billing all need a named owner inside your organization before anything else matters, and transferring them is slow enough that it should start in week 1.
Stabilize: 5 things to land before any feature work
- A rollback you have executed, not one you believe in. Deploy a no-op change on day 2 and roll it back. Discovering the rollback is broken during an incident is the worst possible time.
- Credential inventory and rotation. Every key the departing team held is now a live risk with no owner. Inventory first, rotate in dependency order, and expect at least one integration to break because the key was shared.
- A restore you have actually run. Backups that have never been restored into a scratch environment are a compliance artifact, not a recovery plan.
- Alerting on the 3 signals that mean revenue stopped: checkout error rate, order-write failure rate, and payment webhook lag. Everything else can wait past week 2.
- A dependency freeze plus a triage list. Do not mass-upgrade in week 1, because you will lose the ability to distinguish your breakage from the breakage you inherited.
Point 5 is the one teams argue with. The argument for upgrading immediately is real risk reduction; the argument against is that during weeks 1 and 2 you have no baseline, so every new failure is ambiguous. Freeze, baseline, then upgrade in week 3 with a known-good comparison.
Rescue or rewrite
This is the decision the client actually wants from you, usually by day 10, and it is worth making on evidence rather than on how the code feels to read.
| Signal | Points to rescue | Points to rewrite |
|---|---|---|
| Tests | Any suite that runs, even a thin one | No test can be executed at all |
| Build | Builds from a clean checkout | Needs one specific developer's machine |
| Data model | Recognizable domain entities | Meaning encoded in columns named flag7 |
| Dependencies | 1 or 2 major versions behind | Framework out of security support |
| Change lead time | Measured in days | Measured in weeks and rising |
| Domain knowledge | Someone is still reachable | Nobody can explain a business rule |
| Traffic profile | Revenue-bearing and always on | Low volume and tolerant of a cutover |
Notice that the strongest rewrite signals are about the ability to change the system, not about code aesthetics. A repository full of code you dislike but can build, test and deploy is a rescue.
Rewrites are chosen for team morale far more often than for engineering reasons. The honest test is whether you can name 3 behaviors you would deliberately drop. If the answer is that you would rebuild it exactly, you are proposing a translation, and translations are cheaper as refactors.
The seam-first approach to the first real change
When you do start changing things, pick a boundary rather than a file. Put a measured interface in front of the existing code, route a small share of traffic through the new path, and keep the old path live and warm.
One multi-generation modernization we ran shows the shape. A JSP and CMS-driven storefront moved to React, then to Next.js with micro-frontends so product teams could ship independently, while backend services moved to Spring Boot incrementally and legacy platforms kept serving surfaces that had not migrated yet.
The measurable outcomes were a PageSpeed move from 60 to 90+, P95 page load from 6s to under 2s, and no revenue freeze at any point in the transition. The last item is the one that made the first 2 acceptable to the business.
Seams also give you an exit. If the new path is worse, you route traffic back, and the cost of being wrong is one afternoon rather than one quarter.
What we tell clients about the timeline
2 weeks to observability. 4 to 6 weeks to a first safe change on a revenue-bearing path. A rescue-or-rewrite recommendation at the end of week 2, with the evidence attached rather than a verdict alone.
Anyone promising a first feature in week 1 is either working on a system that was handed over properly, which is rare, or shipping something they cannot roll back. Our longest continuous client engagement has run 8+ years, and it started with 2 unglamorous weeks of exactly this.
FAQ
How much overlap with the outgoing team should we ask for?
2 weeks of paid availability for questions beats 2 days of intensive knowledge transfer. Questions you can ask after you have read the code are worth far more than answers delivered before you have.
What if there are genuinely no tests?
Write characterization tests on the highest-churn files first. They pin existing behavior rather than assert correct behavior, which is what you need when nobody can tell you what correct means.
Should we upgrade dependencies first?
Freeze in week 1, baseline in week 2, upgrade from week 3 in small batches. Mass-upgrading before you have a baseline destroys your ability to attribute any failure.
How do we price work on a system we have not seen?
Price the 2-week assessment as its own fixed-scope engagement with defined deliverables. Estimating the work behind it before that assessment is guessing with an invoice attached.
What is the most common surprise in a handover?
A scheduled job nobody mentioned that does something financially significant. Enumerate cron, queue consumers and webhook handlers on day 1, because they run whether or not anyone documented them.
When is a rewrite genuinely the right call?
When the framework is out of security support, the build is not reproducible, and no one can explain the business rules. Any 2 of those 3 is a hard argument; all 3 makes it obvious.