You built the thing. It shipped. Customers use it. Revenue comes in. And now you spend 80% of your time on technical debt instead of features.
That's not a code quality problem. That's v1 telling you it's done.
I've built four companies. Every single one hit this moment. The product works, mostly. Customers tolerate the rough edges because they're bought in. But the architecture can't absorb what comes next — not because anyone made bad decisions, but because you didn't know enough when you started.
At Superkey, we built an insurance operations platform. V1 shipped fast and iterated faster. We didn't understand the domain deeply enough to design it right the first time, and that was fine — that was the point. V1 was a learning aid. The mistake was not recognizing when the learning was done and the aid had become the problem.
How V1 dies
It doesn't explode. It suffocates.
You notice it when feature requests start taking three times longer than they should. When every change requires touching four other things. When the team spends more time explaining workarounds to customers than building solutions.
At Superkey, the symptoms were specific:
We built for flexibility before we understood the domain. The system could handle any workflow. Nobody could explain what it did. We took feature requests from too many stakeholders with competing goals — each request was a bandaid on a bandaid on a system that was never designed for what it had become.
We skipped the API layer. We used Supabase RPC functions extensively for data access because we were still discovering our entities, access patterns, and boundaries. The plan was always to move to a stable API eventually. "Eventually" dragged on too long, and every client was coupled to database internals. When definitions changed — and they changed often — everything broke.
We rebuilt the extraction pipeline three times. The first iteration used Vellum, a UI wrapper around OpenAI calls. No OCR, no scanned documents — only PDFs with embedded text. The second pass moved to Google Document AI. Expensive and unreliable. The third iteration bought LlamaIndex and discovered we needed to build everything around it anyway — all the orchestration, validation, and domain logic that makes extraction actually work in production. Three stacks, three migrations, same fundamental problem: we were learning what extraction needed by building it wrong.
Our assumptions were flawed in ways we couldn't have known. We thought AI could own more of the process than it can. We thought ERP data would be reliable enough to automate against. We thought the user base would stabilize. None of that was true, and v1 was built on those assumptions.
The 80% line
Here's the heuristic I use: when you're spending more time servicing the system than extending it, v1 is done.
Not 50/50. That's normal — every codebase has maintenance overhead. The alarm goes off at 80/20. When eight out of ten engineering hours go to debugging existing behavior, patching data issues, and explaining limitations to customers instead of shipping the thing that wins the next deal.
At that point, you're not maintaining a product. You're running hospice care for an architecture that can't support what you've learned.
How to kill it
The team wasn't surprised when I said it was time. They were concerned about productivity — rightfully so. A rewrite is months of building with nothing to show customers. If you handle the transition wrong, you lose the team's trust, the customers' patience, or both.
Here's what worked:
Put v1 on life support, publicly. We told the team and stakeholders: no new feature requests on v1. Bug fixes and critical patches only. This sounds obvious but most teams try to run v1 and v2 in parallel, and the v2 timeline doubles because nobody can focus.
Present the migration plan before you start building. The team needs to know this isn't a vanity rewrite. Show the continuity plan — which customers stay on v1, how long, what breaks if v2 is late. Make the constraints visible so the team can hold you accountable.
Start v2 with specifications, not code. This was the biggest difference. V1 started with code and discovered the design through iteration. V2 started with written specs, a designed UI, deep specifications for how the entire system would work, and a standardized API. We wrote the system down before we built it. Not because we're waterfall converts — because we'd already done the discovery. V1 was the discovery phase. V2 was the engineering phase.
V1 was the point
Here's the thing nobody says about rewrites: v1 was the most important thing you built. Not because it shipped to customers — because it taught you what to build next.
Every flawed assumption, every wrong abstraction, every pipeline you rebuilt three times — that's domain knowledge you couldn't have acquired any other way. The Supabase RPC functions that coupled everything to the database? They taught us what our actual access patterns were. The three extraction pipelines? They taught us what extraction actually requires in production. The competing feature requests? They taught us which users matter and which workflows are real.
You can't skip v1. You can't design v2 without having built v1 first. The founders who pretend they got the architecture right on the first try are either lying or building something simple enough that it didn't matter.
The rewrite tax
Every company I've built has hit this. Some people get lucky and their v1 carries them to an exit. Most don't. And the cost of not rewriting is invisible until it's catastrophic — you can't respond to customer requests fast enough, you lose deals to more nimble competitors, and the team burns out maintaining a system they know is wrong.
The pace of shipping keeps accelerating. Five years ago, a sluggish v1 might survive because competitors were equally slow. Today, a two-person team with modern tooling can build in weeks what took your team months. If your v1 is preventing you from winning business, the math is simple: pay down the debt and build v2, or sell the company, because a faster competitor is already coming.
V1 is a learning aid. Treat it like one. Use it to discover what you don't know, document what you learn, and kill it before it kills your momentum.
