The first week with someone else's codebase before we change anything
The previous vendor sent us a GitLab URL, a stale README, and a Postman collection named `OLD_DO_NOT_USE`. The client wants a payment gateway swap and a new reporting tab. We quoted six weeks. The first week is not part of that six — it is the week where we change nothing on production.
We start by getting the app running locally. This sounds trivial. It is not. The last team's docker-compose has a hardcoded reference to an S3 bucket that was deleted in March. The `.env.example` is missing four variables that the code actually reads. The seed script assumes a Postgres version that Ubuntu 22.04 does not ship by default. We document every fix we make to get the app booting, because these are the first artifacts of institutional knowledge that the previous team did not write down.
Once the app is up, we do not look at the features. We look at the database. The schema tells us what the previous team actually cared about, as opposed to what the product spec said they cared about. A `customers` table with 47 columns, where 12 are nullable and always null, tells us something about a scope that was discussed and dropped. A `payments` table with no foreign key to `orders` tells us something about how confident they were — or were not — about the relationship. We write this up as a one-page schema map: tables, foreign keys, indexes that exist, indexes that are obviously missing, and columns whose names suggest business meaning we cannot confirm yet.
Then we read the code, but not all of it. We read the request paths for the two things the client wants changed. The payment gateway integration is a single file, 1,400 lines, with a switch statement on `provider` that has three cases. Two of those cases are for gateways the client no longer uses. The reporting tab they want added touches a different part of the codebase — a Rails controller that queries a view called `monthly_summary` whose definition lives in a migration file from 2021. We trace both paths end to end and write down every file they pass through. This becomes our change-surface map.
We do not run the test suite yet. We look at what it covers. The previous team has 230 tests, but 180 of them are model validations and factory checks. There are 12 request specs, and 4 are skipped with a comment that says `TODO: fix after rails upgrade`. The rails upgrade happened in 2022. We note this and move on. We will write tests for the paths we are about to change, but we do not try to fix the existing suite in the first week. That is a trap. You start fixing tests, and suddenly you are refactoring a test helper that depends on a factory that references a deleted model, and the week is gone.
The last thing we do is deploy to staging. Not our staging — the client's. We want to see what their CI does, what their deploy script assumes, and whether the staging database is a real copy of production or a 40-row sample from 2022. We deploy the current `main` branch without any of our changes. If this deploy fails, we need to know now, not on the day we are trying to ship the payment gateway swap.
By Friday of that first week, we have four documents: the local setup notes, the schema map, the change-surface map for the two features, and the deploy notes. We have not written any application code. We have not changed anything in production. We have not sent the client a status update that says "we are making progress" — because we are not yet, and saying so would be dishonest.
What we have is enough context to start on Monday with a real estimate for the first feature, and a list of questions for the client that are specific enough to answer. "How does your payment reconciliation work" is not a useful question. "The `payments` table has a `reconciled_at` column that is null for 3,400 of the last 10,000 rows — is that a backlog or is reconciliation manual" is a question that gets an answer in one email.
The previous vendor spent two years building this system. We spend one week understanding it before we touch it. That ratio is what makes the six-week estimate hold up.