On The 8 Spot

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

Download the long edition (EPUB, 30 KB)

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 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.

  1. The old application set in its original repositories.
  2. The same applications being redeveloped by a contractor under a signed project plan.
  3. The same applications carried inside the resilience project.
  4. 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.

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  8. 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.
  9. 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:

Other items were not blockers but moved the dates:

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

What was left open

Takeaways

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. Question the migration method early. The assumed approach, restoring a dump, was wrong at that scale, and finding that on day two saved months.
  6. 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.
  7. 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.