Inherited Codebase Checklist for Freelancers and Agencies

Taking over a client codebase is risky because the first problems are usually invisible: missing environment variables, hidden coupling, weak tests, expired dependencies, and business logic nobody can explain.

Use this checklist before you quote the work, commit to a timeline, or promise a cleanup plan.

1. Confirm the repo can be understood

Start with the boring facts:

• Languages, frameworks, package managers, and lockfiles
• App entry points, routes, jobs, webhooks, and scheduled tasks
• Database models, migrations, and external services
• Deployment target and CI/CD configuration
• Environment variables and secret handling

If you cannot describe how the system starts, stores state, and talks to the outside world, you are not ready to estimate it.

2. Find operational hazards first

Before style issues, look for things that can break production:

• Committed secrets or private keys
• Missing auth checks on API routes
• Unpinned dependencies or missing lockfiles
• No backup or migration story
• No tests around billing, auth, permissions, or payments
• Manual deployment steps that live in someone's head

These findings change the quote because they are not cleanup. They are risk containment.

3. Separate noise from roadmap

An inherited repo can produce hundreds of complaints. Most are not worth showing a client.

Group findings into a short roadmap:

The client does not need a dump. They need to know what blocks trust, what slows delivery, and what can wait.

4. Turn the audit into a paid deliverable

For agencies and freelancers, the audit should not be unpaid discovery. A good handoff package includes:

• Executive summary
• Architecture map
• Health and risk scores
• Top 10-15 findings with evidence
• 30/60/90-day repair plan
• Optional GitHub issues for accepted work

What to say before quoting

The safest client language is direct: "I can estimate the audit now; I can estimate the repair work after the audit." That separates discovery from implementation and avoids pretending the unknown codebase is already understood.

If the client needs a number immediately, quote a bounded review: repository access, build/test attempt, architecture map, top risks, and a prioritized plan. Then turn the accepted plan into implementation milestones. This keeps trust high because every later estimate is tied to evidence rather than optimism.

When to walk away or pause

Pause the engagement if the client cannot provide repository access, deployment context, owner contacts, or permission to inspect critical flows. Walk away from fixed-price cleanup when production access, billing behavior, or data-loss risk is unknown and the client refuses discovery. Unknown risk is not a small implementation detail; it is the work.

This is exactly where CodeTruss is designed to fit: connect the repo, generate the map and report, then turn accepted findings into GitHub issues or fix PRs. Audit your first repo free.