Inventory on a Copy, Touch Nothing Live

Mostafa Dhouib·8 min read

Inventory on a Copy, Touch Nothing Live

The short answer. The first milestone of a legacy replacement should run entirely against a copy of the production database, touch nothing live, and deliver no features at all. That sounds like a waste of a milestone and it is the opposite. Because there is no operational risk in the work, it can be done exhaustively, and exhaustiveness is the only thing it is for. The deliverable is a written inventory of what the old system enforces and a list of rules with no owner in the new design. Selling it requires naming an acceptance test for a document, pricing it as a fixed small piece, and making clear it is the gate that prices everything after it.

Every replacement project has a first milestone, and in most of them it is a feature.

Sign the contract, pick a module, build it in the new stack, demonstrate it. The logic is that the client wants to see progress and progress means software. It is a reasonable instinct and it puts the riskiest unknown in the project behind the first thing you build rather than in front of it.

Why the copy is the whole trick

Running against a copy changes the economics of the work rather than its content.

On production, any investigation is constrained. You cannot run an expensive catalogue query during business hours. You cannot enable statement logging to see what actually executes. You cannot replay traffic. You cannot deliberately violate a constraint to find out what it rejects. Every one of those is the fastest way to learn something, and every one of them is off the table.

On a copy, all of it is available and none of it can hurt anyone. You can break the copy. You can restore it and break it differently. You can run the same procedure with twenty variations of input and record what comes back.

So the copy does not make the inventory cheaper. It makes the inventory possible to do properly, and an inventory done properly is a different artefact from one done carefully around a live system.

What the milestone actually delivers

Four things, all of them documents, all of them specific enough to be checked.

The object inventory. Every stored procedure, trigger, constraint, default and view, with its source, its dependencies and a plain English statement of what it enforces. Extracted from the system catalogue rather than assembled by hand, so the population is complete by construction.

The unowned rules list. For each rule classified as policy rather than plumbing, whether anything in the proposed new design accounts for it. The entries with nothing against them are the finding. This list is the reason the milestone exists.

The locale and encoding report. The results of actually loading a sample through the proposed pipeline and comparing values, not row counts. Date handling, character encoding, numeric precision, time zone treatment. These are the failures that pass every structural check, so they have to be tested explicitly on the copy before anything depends on them.

A revised estimate for the rest of the work. Not a reassurance. A number derived from the inventory, with the parts that grew named and explained.

That fourth item is what the client is buying, even though the first three are what they receive.

How to scope it so it ends

The standing objection to a documentation milestone is that it has no natural finish. Someone can always read one more procedure.

The answer is to define completion against the population rather than against understanding.

Completion is every object in the catalogue appearing exactly once in the inventory, with a classification and a statement. For objects that are genuinely opaque, the statement is allowed to be that the behaviour could not be determined and here is what was tried. An honest unknown is a complete row.

That makes the milestone finite, countable and checkable on the day. The client can verify the deliverable without being able to evaluate the analysis, which matters, because they usually cannot evaluate the analysis and should not have to.

How to sell it

The commercial conversation is the hard part, not the technical one. A few things make it work.

Price it small and fixed. This milestone should be the smallest paid piece of the engagement. Its job is to price the rest, so it cannot be large enough to feel like a commitment to the rest.

Say out loud that it ships no features. If you let the client discover that at delivery, you have mis-sold it. If you say it in the first conversation, it becomes the distinguishing feature rather than a disappointment. The sentence that works is that this milestone cannot break anything, because it does not touch anything.

Name what happens if the finding is bad. The useful framing is that the inventory can tell you the replacement is larger than the budget, and discovering that now costs one small milestone rather than two thirds of a project. A client who understands they are buying the option to stop will buy it.

Attach it to the thing they already fear. Most organisations in this position have a specific memory of a system change that went wrong. The inventory is the answer to that memory, so connect the two explicitly.

Give them the artefact regardless of what follows. The inventory is a written description of the organisation's own rules, which most companies in this position have never had. It has value if the replacement goes ahead, if it is deferred, and if they take it to a different supplier. Saying that plainly is more persuasive than any assurance about your own work, because it is verifiable.

What this milestone is not

It is not a feasibility study, and the distinction matters when writing the statement of work.

A feasibility study answers whether something can be done. This answers what is there. Those produce different documents, and conflating them lets the deliverable drift towards opinion, which is exactly what makes a documentation milestone hard to accept.

It is also not an architecture for the new system. Designing the replacement using the inventory is the next piece of work. Mixing them means the inventory's completeness gets traded off against design progress, and the inventory loses that trade every time.

The honest limit

A copy is a copy of the data that exists, which is the binding constraint on everything above.

A rule that only fires on a condition absent from the copied data will be read correctly and never observed. You will record that the branch exists and have no way to learn how often it is taken or what it does in anger. Thoroughness against the catalogue does not convert into completeness against reality, and claiming otherwise is how this milestone gets oversold.

There is a second limit worth stating to clients. The inventory is a snapshot. If the old system continues to be maintained during the replacement, and it usually must be, the inventory starts drifting the day it is delivered. That is manageable with a small process for recording changes to the old system, and it is unmanageable if nobody expected it.

FAQ

What is the first milestone of a legacy replacement? An inventory produced entirely against a copy of the production database, touching nothing live and delivering no features. It enumerates every stored procedure, trigger, constraint, default and view, classifies each as policy or plumbing, and produces a list of rules with no owner in the new design. It also produces a revised estimate for the remaining work.

Why does running against a copy matter so much? Because it changes what investigation is permitted. On production you cannot enable statement logging, replay traffic, run expensive catalogue queries during business hours, or deliberately violate a constraint to see what it rejects. On a copy all of that is available and none of it can harm anyone, so the work can be exhaustive, and exhaustiveness is the entire value of the milestone.

How do you stop a documentation milestone running forever? Define completion against the population rather than against understanding. Every object in the system catalogue appears exactly once in the inventory with a classification and a statement, and an honest unknown counts as a complete row provided it records what was attempted. That makes the deliverable countable and checkable by a client who cannot evaluate the analysis itself.

How do you sell a milestone that ships no software? Price it small and fixed, say in the first conversation that it ships no features, and frame it as the purchase of an option to stop. The inventory can reveal that the replacement exceeds the budget, and learning that after one small milestone is cheaper than learning it two thirds of the way through a build.

Is this the same as a feasibility study? No. A feasibility study answers whether something can be done. An inventory answers what is actually there. Keeping them separate in the statement of work matters, because conflating them lets the deliverable drift towards opinion, and an opinion is much harder for a client to accept as a milestone than a complete enumeration.

Does a thorough inventory guarantee a safe migration? No, and the limit is structural. A copy contains the data that exists, so a rule that only fires on an absent condition is read accurately and never observed in effect. The inventory reduces how much gets discovered in production rather than eliminating it, and it is also a snapshot that begins drifting as soon as the old system is next maintained.