What We Look For in a Codebase We Did Not Write
A working note on inherited codebase assessment — what matters, what does not, and where these projects usually go sideways.
The question we get asked about inherited codebase assessment is usually "which option is best". The better question is "what breaks first". This post walks the order we actually use.
The problem underneath
The pattern is familiar. Someone raises it in a standup, a decision gets made in ten minutes, and nobody records why.
Six weeks later three people hold three different mental models. The rework costs more than the original choice ever did.
What this looks like in real projects
In projects like these, one version is local. A single workflow strains, everything else is fine, and two focused weeks clear it.
The other reads identically in a status update, but the strain is systemic. Treat that as local and you spend a quarter arriving back where you started.
Mistakes companies make
- Choosing tools before the workflow is written down.
- Scoping version one to cover every edge case.
- Leaving the work unowned, then blaming the tool.
- Skipping measurement, so nobody can prove it helped.
- Treating launch day as the end of the cost.
The first and the last are the expensive ones.
The engineering view on inherited codebase assessment
From inside the codebase, inherited codebase assessment reduces to three questions. What happens when a step fails halfway. Who finds out. How you reverse it.
Design for partial failure before you need it. Step three fails after one and two succeeded, and that is the case people skip.
Give retries a ceiling and some jitter. A retry storm is an outage you built yourself.
How we approach it step by step
- Write the current process down, step by step, including the manual bits.
- Mark which steps must be exact and which can be approximate.
- Choose one step to change this month.
- Instrument it before and after.
- Hand it to one real user and watch, without helping.
- Fix what they got stuck on, then widen.
Practical guardrails
- One environment that mirrors production closely enough to trust.
- A rollback you have actually run, not one you assume works.
- A short written scope with an explicit out-of-scope list.
- A number that tells you whether to continue.
Trade-offs worth saying out loud
Every option here buys something and sells something. Buying simplicity now often sells you optionality in a year, and that is frequently a good deal.
The bad deals are the ones nobody priced.
Common misconceptions
“This is a small change.” Small in code, sometimes large in support, billing, and docs.
“We can decide once we have more data.” Often the data only arrives after you decide.
“Nobody will use it wrong.” Someone will, on day one, and they will be your best customer.
Frequently asked questions
Do we need to hire someone for this?
Not at the start. One named owner with a few protected hours a week, plus a small build team, is enough to prove value.
How long does inherited codebase assessment take to get right?
A narrow first version is usually four to six weeks. Anything quoted at three months with nothing shippable in between is a risk, not a plan.
When should we revisit the decision?
When a second customer asks for something the first never needed, or when volume changes by an order of magnitude.
What is the most common mistake with inherited codebase assessment?
Deciding it in a hurry and never writing down why. The choice is usually fine; the missing context is what costs money.
Can we start without changing the whole system?
Almost always. Pick one workflow, ship it end to end, and keep the old path available until the new one earns trust.
Conclusion
The useful move on inherited codebase assessment is almost always the smaller one. Ship a narrow slice a real user can touch this month, measure it, then decide what earns the next four weeks.
Everything gets easier once something is live.
Related reading and next steps
- growth analytics — how we run this kind of work.
- custom AI solutions — how we run this kind of work.
- More writing from the team.
Want a second opinion on inherited codebase assessment for your setup? Book a 30-minute call. If it is not worth building, we will say so.
FAQ
Frequently asked questions
Do we need to hire someone for this?+
Not at the start. One named owner with a few protected hours a week, plus a small build team, is enough to prove value.
How long does inherited codebase assessment take to get right?+
A narrow first version is usually four to six weeks. Anything quoted at three months with nothing shippable in between is a risk, not a plan.
When should we revisit the decision?+
When a second customer asks for something the first never needed, or when volume changes by an order of magnitude.
What is the most common mistake with inherited codebase assessment?+
Deciding it in a hurry and never writing down why. The choice is usually fine; the missing context is what costs money.
Can we start without changing the whole system?+
Almost always. Pick one workflow, ship it end to end, and keep the old path available until the new one earns trust.
Building something similar?
Let's talk in 30 minutes.