How I Rescue Dead Codebases

You get the Slack message. Or the email. Sometimes it's a frantic founder, sometimes it's a new client who fired their last dev. The message is always some variation of:

"We have a project. The developer left. We need someone to pick it up."

I've been that someone more times than I can count. Over the years I've built a repeatable process for walking into a stranger's codebase and figuring out — fast — what's salvageable, what's broken, and what needs to be burned down and rebuilt.

Here's exactly what I do.

Step 1: Get access to everything before touching anything

Before I write a single line of code, I need:

• Full repo access (not just read — write and admin)
• Every .env file or access to the secrets manager
• Hosting/deployment credentials (Vercel, AWS, whatever they're using)
• Any existing docs, Notion pages, Loom recordings, Figma files
• Access to the database (read-only at minimum)

This sounds obvious but clients often forget. The previous dev sometimes held everything hostage, or just disappeared. Getting access can take days. Start immediately.

Step 2: Run it locally in under 30 minutes

If I can't get the project running locally in 30 minutes, that's my first red flag. A well-built project should have a README that actually works. If the README is missing, outdated, or the setup requires 14 manual steps — that tells me a lot about how the rest of the code was written.

git clone [repo]
cp .env.example .env.local
npm install
npm run dev

If any of those steps fail, I document exactly where and why. That becomes part of my audit report.

Step 3: Read the git history like a detective

git log --oneline --graph

The commit history tells a story. I'm looking for:

• Commit frequency — did the dev work consistently or in frantic bursts?
• Commit messages — are they descriptive or just "fix" and "update"?
• Last commits — what was the last thing they touched before disappearing?
• Branch structure — is there a main, a dev, a graveyard of feature branches never merged?

Step 4: Map what actually exists vs what was promised

I ask the client for the original spec or scope document. Then I map what's actually built against what was promised using a simple three-column table:

Feature	Status	Notes
User auth	Done	Uses NextAuth, seems stable
Dashboard	Partial	UI exists, no real data
Payments	Missing	Stripe keys in .env but no integration
Email notifications	Missing	Not started

This is the most valuable deliverable I give a client. It's the first time many of them understand what they actually paid for.

Step 5: Check the scary stuff

Hardcoded secrets — run:

git grep -i "sk-"
git grep -i "secret"

Outdated dependencies:

npm outdated

Sloppy code signals:

grep -r "console.log" src/
grep -r "TODO" src/

A codebase with 200 console.log statements was written fast and never cleaned up.

Step 6: Write the audit report

After 2–4 hours of this, I write a clear report:

1. What works — things I'd leave as-is
2. What's broken — bugs and missing features
3. What needs a rewrite — architecture decisions faster to redo than fix
4. Timeline and cost estimate — based on all of the above

This report goes to the client before any money changes hands. It protects them and it protects me.

The most common things I find

• No error boundaries — the app crashes completely on any unhandled error
• No loading states — async calls with zero UX feedback
• Hardcoded data — things that should come from a DB are copy-pasted in components
• TypeScript with "any" everywhere — same as no TypeScript
• One massive 1,200-line component that does everything
• Missing mobile styles — the dev only ever tested on their MacBook

When to recommend a full rewrite

I recommend a rewrite when fixing the existing code would take longer than rebuilding it — and when the architecture itself is the problem, not just the implementation. Bad folder structure, no separation of concerns, business logic inside UI components. These aren't bugs. They're foundations, and you can't fix a foundation by patching walls.

The honest truth about inherited projects

Most abandoned projects aren't abandoned because the idea was bad. They're abandoned because the wrong dev was hired, the scope wasn't managed, or the communication broke down. The code is usually fixable. What's harder to fix is the client's trust — in developers, in the process, in their own idea.

That's why the audit report matters more than any code I write in week one. It's proof that someone is finally being straight with them.

If you have a project in this situation — let's talk.