Inherited code · 2026-11-12 · 5 min read

You inherited a codebase with no documentation. The first five days.

No README, no onboarding doc, no one left who built it. Here's what to actually do in the first week, in order, before you touch a single line.

Mohit Tanwani

Mohit Tanwani
Founder, Tech Mitrise

The short version

Don't start fixing things on day one. Spend the first days finding the critical path (what actually makes money or keeps customers from leaving), the undocumented business rules living in the code, and whatever passes for a rollback plan today. Only after that do you add tests and start changing anything — and the first changes should be the smallest ones that prove you understand the system, not the biggest ones that impress someone.

Resist the urge to start fixing things

The instinct when you inherit an undocumented system is to start cleaning it up — rename the confusing variable, delete the dead-looking code, upgrade the obviously outdated package. Every one of those instincts is reasonable and every one of them is premature in week one, because you don't yet know which parts of the mess are load-bearing.

Undocumented systems accumulate rules nobody wrote down on purpose: a discount that only applies if an order has exactly one line item, a date comparison that's off by a day because it was patched around a timezone bug years ago, a "dead" code path that's actually how one large customer's integration still works. You cannot tell which of these are safe to touch by reading the code alone. You have to go looking for evidence first.

The first five days are about building a map, not fixing anything. The map is what makes the fixes safe later.

Day by day: what to actually do

Day 1 — find the critical path, not the whole system. Don't try to understand everything. Ask: what are the two or three flows that, if they broke right now, would cost money or customers within hours? Usually it's something like checkout, login, or whatever triggers billing. Trace just those paths from entry point to database write. Everything else can wait.

Day 2 — find out what's actually running in production, not what the repo says. Check the real deployed version, the real PHP/framework version, the real cron jobs and queue workers that are active — not the README's claims. A surprising number of inherited systems have scheduled jobs or workers nobody remembers configuring, still running, still mattering.

# A few honest, low-risk starting commands (Laravel/PHP example)
php artisan about            # framework, PHP version, drivers actually in use
php artisan schedule:list    # every cron-driven task actually registered
crontab -l                   # what the OS is actually running, independent of the app
php artisan queue:failed     # evidence of what's already quietly broken

Day 3 — find the undocumented business rules. These live in if statements, not comments. Grep for hardcoded IDs, hardcoded dates, and suspiciously specific conditionals (if ($customer->id === 4821), if ($total === 0 && $items->count() > 1)). Each one is a clue that something specific happened once and someone patched around it instead of modelling it. Write these down as you find them — this list becomes the thing you protect, not the thing you clean up first.

Day 4 — find out what "rollback" currently means, if anything. Can this system's last deploy be reverted in minutes, or does "rollback" mean restoring a database backup from last night and losing everyone's work since? Check whether migrations are reversible, whether there's a tagged release to go back to, and whether anyone has actually tested a rollback recently rather than just assuming one exists.

Day 5 — write down what you now know, and what you still don't. A short internal document: the critical paths, the undocumented rules you found, what's actually running, and the real rollback story. This is the artifact that makes everything after this week faster, because the next person (including future-you) doesn't have to re-derive it.

Not sure where your system stands?

A 20-minute call with the founder will tell you whether this applies to you and what to do first.

What changes first, and why

The first real change you make should be small enough to be boring: add one test around a critical path you traced on day one, or fix one bug you're now certain is safe to fix because you understand its blast radius. Resist the temptation to prove your value with something big and visible — the goal in week one is to demonstrate, to yourself and to whoever you report to, that changes here are now evidence-based instead of hopeful.

From there, the sequence that actually reduces risk is: tests around the critical paths first, then observability for the failure modes you can't test for (because they depend on real traffic patterns), then a verified rollback path, and only then larger changes like upgrades or refactors. Doing this in the opposite order — upgrading first, testing later — is how undocumented systems turn a routine framework upgrade into an outage.

A note on what this describes: this is general methodology built from patterns that repeat across inherited PHP/Laravel/Yii systems, not a specific client's story — no client names, dates, or outcomes are referenced here. If you want to talk through where your own system actually stands against this, that's what a Critical Software X-Ray is for.

Mohit Tanwani

Written by Mohit Tanwani

Founder of Tech Mitrise. He does the rescue and upgrade work described here. 10+ years building, running and repairing production software, mostly in PHP, Laravel, Yii, MySQL and AWS.

About the founder

This is general methodology, not a specific client engagement — see the note at the end of this article on what is and isn't illustrative here.

Keep reading

ReferencePayment succeeded, access denied: tracing a webhook failure end to endHow we helpBook a free 20-minute triage