Planning a forced vendor transition in two days: from four versions of one app set to a gated, dated plan
A case study in turning a contract constraint into a scoped plan, a schedule, a deck and a first working API, while checking every claim against the code
At a glance
| Situation | A national credit bureau's incumbent system could be renewed only for a short, fixed term, while its replacement would not be live in time to cover it. An in-house pipeline had to become an interim system that covers everything the incumbent does |
| Approach | Pin down what "the apps" meant, date each version, test the interim system against a verified gap list, then plan, schedule, scope and brief leadership from that list, and start closing the largest gap |
| Window | 28 to 29 October 2026 |
| Output | A four-version roadmap with Gantt charts, a one-page plan, a checklist set (per person, system, task and scope), a schedule and calendar, a 13-slide leadership deck, markdown copies of two vendor documents, a documented inventory of the incumbent's functions, a REST service covering most of them with 24 new tests, advice on a very large database migration, and a legacy-data load with two sample reports |
| Method | The consultant set direction and made every decision. Claude Code read the repository and documents, wrote and ran the code, and built the documents |
| Status | Plans and documents delivered for review. The REST service and the PII-checked commit are local and not pushed. Several dates remain assumptions, and the plan marks them |
The situation
The bureau runs a credit information system supplied by an outside vendor. Two things changed at once.
- The incumbent's contract. It could be renewed only for a short, fixed term, and the system stops working when that term ends.
- The replacement's timing. The next-generation system, procured separately, would not be live early enough to cover the whole renewal period.
The consultant's team had been building a data pipeline for the bureau: ingestion of lender submissions, quality checks, duplicate removal, multi-pass matching of subjects, and report generation. The original plan had been modest: document everything for the next-generation project, fix security issues in the existing systems, and run the pipeline as a second instance for a REST API and a report maker, so the incumbent could concentrate on ingestion.
That plan no longer held. The second instance had to become an interim system, informally "version 1.5", that could replace everything the incumbent does until version 2.0 went live. It had to carry ingestion, deduplication, matching and an API for report generation, and run in parallel with the incumbent as soon as it was ready.
A second problem sat underneath. People used one phrase, "the core apps", to mean four different things.
- The old application set in its original repositories.
- The same applications being redeveloped by a contractor under a signed project plan.
- The same applications carried inside the resilience project.
- The same applications folded into the next-generation system.
Until those were separated and dated, nobody could say what was in scope for which team.
How the work was run
The session ran for about two days. The steps below are in the order they happened.
- Find the files, and say when they are not there. The first question was whether the repository held the core apps. It did not: a search found only written references in decision logs. Claude said so and asked where the sources were, instead of describing apps it had not seen. The consultant pointed to a folder of legacy repositories and to two vendor PDFs, a 22-page inception report and a 40-page project management plan.
- Define the four versions, then date them. The first roadmap was a Word document with a month-by-month Gantt chart for the contractor's version taken from the plan, and undated lanes for the others. The consultant then supplied dates: a start for the next-generation contract, a build phase with no operate phase after it, and a delivery window for the resilience version that their own team would deliver independently of the contractor. Each correction was applied to the tables and the charts. A high-level chart with one bar per version went into section one.
- Convert the source PDFs to Markdown so the schedule could be checked against text, not memory. The conversion tool failed to import, so Claude built the conversion directly from PDF text and table positions, cleaned up empty merged-cell columns, and used the result to replace an earlier "confirm the exact days" caveat with the real acceptance dates.
- Re-plan around the constraint. The consultant pasted the original three-point plan and the changes. Claude compared them point by point, and then checked the pipeline repository for what already existed. This was the key step: report generation and the legacy migration scripts existed, but neither was at the scale the new plan needed.
- Turn the plan into review material. From one conversation came a one-page plan with leadership and two team scopes, a transition checklist (approvals, legal and security, communication, technical gates, onboarding of the entities that use the bureau's data), a four-way checklist set to help the consultant scope the work, a schedule and a month-by-month calendar. Business matching and business migration were added to the scope when the consultant said they were still to do. A dated list of contract start and end dates was added to both documents.
- Brief leadership. A 13-slide deck was built for the next day's presentation. The environment could not render slides, so the file was checked structurally and the consultant was told to page through it before presenting.
- Close the biggest gap. The consultant asked for the incumbent's functions to be documented and for a REST version of them to be scoped and built. Claude read the vendor's manuals, wrote the capability and scope document, and built a service with nine endpoints: four enquiry functions (new application, monitoring, application update and consumer), an enquiry summary, alerts, two domain lookups and a health check. The service uses API keys tied to provider, branch and user, per-function permissions, idempotent replay, the incumbent's mandatory-field rules, and an OpenAPI description. Tests ran against a real throwaway PostgreSQL, including the bureau's own published sample subject.
- Check the numbers before advising. For the full-scale migration, Claude read the migration scripts and the existing notes before answering. The scripts had run only on a small sample. The real database was in the range of 10 to 20 terabytes.
- Handle real data with care. When a legacy export arrived on a USB drive, Claude verified its checksum, copied it into a folder outside the repository, started a separate throwaway PostgreSQL on its own port, loaded the export, and generated two sample reports without touching the main database.
What the checking found
The interim system's gaps, verified in code
Before any dates were promised, the repository was searched for each capability the plan relied on. Five items were blockers for go-live:
- No report API existed. Report generation was a command-line tool. A search found no web framework anywhere in the code.
- Real encrypted submissions were not handled. The main run path still read files directly, so only already-decrypted files worked.
- No parity test against the incumbent. Recall and agreement figures compared the pipeline with its own output or a truth set, not with the live system. Without that, there was no objective go or no-go criterion.
- Migration had only run on a sample. The loading schema was not part of the normal migration step, so it would not survive a database rebuild.
- Legacy reports covered individuals only. Company subjects raised an error.
Other items were not blockers but moved the dates:
- Monthly matching speed. A projection of more than a day of processing on one worker for the full-size residual was a linear extrapolation, not a measurement.
- Company matching. It was built but switched off and uncalibrated. A shadow run in early October would have auto-confirmed 96.6% of 36,525 staged companies on name and address alone. There was no labelled set of company duplicates, and almost none of the staged companies carried a registration number.
- Sole-trader linkage. It was built but off, and in the small sample it linked far more subjects than there were standalone companies, so it might matter more than company matching.
The schedule squeeze
With the incumbent's term short and the interim system ready only late in it, the parallel run was a few months at most. Any slip in the interim go-live came straight out of that window. The next-generation go-live also fell inside the parallel run, and the plan could not say whether the interim system was meant to hand over to it at that point. Both questions were put in the deck for the first review.
Hardware and sizing
When the consultant said the second instance would run on-premises, Claude pulled sizing from the repository's own benchmarks: a planning target of a mid-sized multi-core server with plenty of memory and fast storage, plus several terabytes of data with a recommended buffer. Memory was the real constraint. Fuzzy deduplication peaked at tens of gigabytes on the largest providers, matching with four workers tripped a memory kill switch even on a large-memory host, and two workers was the validated safe limit. A database crash on the Windows development hosts recurred every few days. Debian was the target, but the repository could not confirm that the crash would not follow, so the plan treats it as a check in the first burn-in.
The migration advice
The consultant's assumption was to restore a dump. Claude's answer, after reading the scripts, was to read the live database over a normal connection instead, and not production itself. At that size a dump needs an enterprise database instance with far more tablespace than the free container allows, and the restore alone could take days. Production would be competing with real enquiries, so the plan asks for a read-only copy: a standby, a snapshot or a restored copy. The script needed work first: it was single-stream, one table at a time, had no resume, and reconciled by row counts only. The advice listed an inventory of segment sizes, parallel loading by table and row range, a resume manifest, per-chunk reconciliation, throttling and encrypted transport. It also pointed out that most of 12 TB was probably history, logs and large objects the new system may not need.
Two sample reports and a real defect
The sample legacy export loaded into the throwaway database with 36 tables and a few tens of thousands of subjects. The individual report ran to 81 pages and read correctly. The company report had a real bug: it listed 12 contracts and printed 12 detail pages for a subject with only four contracts. The cause was a join to a history table that holds one row per monthly submission, so each contract fanned out. The fix was described, not applied, until the consultant decided. A page renderer was installed to inspect layout, and two pages of the individual report were viewed to confirm the layout.
Where it went wrong, and how it was handled
- A misread request. Asked for a Gantt chart for "no 4", Claude drew version 04's schedule. The consultant had meant section 4, the same-scope comparison. The chart was redrawn as one row per system with the versions as bars, and a legend and label fix followed.
- Assumed dates. The incumbent's exact end day, the contractor's notice-to-proceed date and the length of the interim team's contract were not in any document Claude had. The plan states the assumed values (the incumbent's term ending around the same time as the contractor's engagement) and the last deck slide lists them for confirmation.
- Stale assumptions about contract length. The first version-04 dates assumed a longer contract with an operate phase after the build. The consultant corrected this to a build phase and nothing after, and the milestones for later phases were dropped.
- Unverified output. The roadmap, plan, checklists and deck were never opened in Word or PowerPoint, because the tooling to render them was not available. Every handoff said so, and asked the consultant to page through them.
- Roles. The leadership roles were rewritten after the consultant corrected who led what, and the split between two of the people was left as "to be set" in the document, not guessed.
What was left open
- Exact start and end days for the incumbent's renewal, and the contractor's start date.
- Whether the interim system hands over to the next-generation system at its go-live, or runs on.
- Whether business matching and sole-trader linkage are in scope, and which callers the report API serves.
- The company-report join defect, the raw-code labels in the reports, and the full-scale migration, none of which were implemented in this stretch.
- Security review of the API before any exposure, key custody for decryption, and hardware procurement lead time.
Takeaways
- Name the thing before you plan it. Four meanings of "the core apps" meant four plans. Separating them took a short table and made every later document consistent.
- Put dates on assumptions and keep a list of them. Each date the plan took from the consultant, and not from a signed document, was marked. That is what turns a confident schedule into a reviewable one.
- Verify capability claims in the repository before promising a date. The gap list came from searching the code, not from recollection, and two of its entries (no API framework, decrypt not wired) shaped the plan.
- Measure against the system you are replacing. Agreement with your own output is not parity. A comparison with the incumbent is the only credible go or no-go gate.
- Question the migration method early. The assumed approach, restoring a dump, was wrong at that scale, and finding that on day two saved months.
- Keep real data out of the repository. The legacy export lived outside the repo, in a separate database, and the PII check held back eight files with contact details or internal addresses.
- Say what you could not check. Every document handoff stated what had not been rendered or run, which made the consultant's own review faster.
About these numbers
Counts, durations and test figures come from the session's tool output: the repository searches, the manuals, the test runs and the generated files. Dates other than those the consultant supplied are marked as assumptions in the plan itself. Sizing and performance figures come from the repository's benchmark notes and are single-host measurements or extrapolations. The company-matching shadow-run figure is from an early October test on staged data and is not a measure of real accuracy. Vendor, bureau, people and contract names are deliberately left out, and no contract dates are given.