Cycles Inside A Waterfall · The Reluctant Guide to Shopify Migrations

Launch day, hour nine in the morning. Greycott’s internal QA team—three people from operations, two from the content side, all of whom have spent five months hearing about the migration and none of whom have logged into the new admin before—receive the staging URL and a checklist in the same email. The checklist has forty-one items. The admin has, as far as they can tell, several thousand things in it. They open a product. They are not sure whether the price they’re looking at is the one customers will see, or the one a Market is overriding, or the one an app is about to change. They are not sure where to look to find out. They have thirty-six hours.

The launch goes as well as a launch can go when the people testing it met the thing they were testing that morning. Which is to say it goes fine, in the way a flight goes fine. Two weeks later the operations team finds six things—a wholesale price band that rounds wrong, a gift-set bundle that decrements the wrong inventory, a customer-group tag that didn’t carry over—that QA would have caught in an afternoon, if QA had been living in the admin for a month instead of visiting it for a day. None of the six is a development bug. Every one of them is a thing you only see when you try to do your actual job in the new system, and nobody had tried to do their actual job in the new system.

That is the failure this chapter is about, and it is not a testing failure. It’s a scheduling one.

The previous chapter argued that the order of operations on a Shopify migration is more waterfall-shaped than most teams want it to be—that the big architectural commitments have to land at the front, in sequence, because getting the sequence wrong compounds. All of that is true and none of it should be confused with permission to run the project itself as a single five-month pour of concrete.

Order of operations is waterfall. The day-to-day cannot be. A sequenced project that executes as one long black box, head-down, demo-quiet, opens its doors at the end onto a panicked QA phase and a launch nobody in the building actually believes in. The discipline that keeps a team out of that box is cycles—short, visible loops inside the larger sequence—and the thing those cycles are for is not velocity. It’s contact. The team stays in contact with the thing it’s building, and the people who will have to run it stay in contact with the thing they’ll have to run, weeks before the day it becomes theirs.

The cleanest way to see why this matters is to stop treating development, assembly, and QA as one undifferentiated stretch of “building.” They are three different problems, and the project plans that come to grief are the ones that budgeted for the first and assumed the other two were the same thing wearing different hats.

Development is building the parts. A product page. A wholesale pricing rule. A subscription flow. Each part can be built, reviewed, and demoed on its own, and when it works on its own, the ticket closes and the burndown chart is happy. This is the phase every project plan is good at, because it’s the phase that looks most like the custom builds everyone came from. The parts work.

Assembly is what happens when the parts have to be a store. Real product data, all eleven thousand SKUs of it, not the six tidy samples the PDP was demoed against. Real merchandising—the gift sets, the wholesale bands, the seasonal collections, the way Greycott’s catalog actually hangs together rather than the way the data model imagined it would. Real edge cases, which is just a polite name for the conventions a brand has accreted over six years on the old platform and never wrote down. A product page that renders is development. A product page an operator can actually run, with the merchandising logic she expects and the inventory behaving the way the warehouse behaves, is assembly. Most of the value of the migration lives in that second sentence. So do most of the surprises. The parts work; the system doesn’t, yet—and the gap between those two clauses is where projects that thought they were nearly done discover they are not.

A workbench covered in perfectly made but completely unassembled mechanical components, each in its own tray, with a hand hovering above them as if unsure where to begin. — The parts all worked. The system did not, yet.

QA is the third problem, and it is the one teams reliably misfile. QA is not a fresh laptop and a checklist and a person who has never seen the admin clicking through forty-one items in an afternoon. That isn’t quality assurance; it’s a smoke test wearing a serious expression. Real QA on a migration is the internal team using the new system as their daily tool—not testing it, operating it—and discovering, through the friction of trying to get their actual work done, all the places where the system’s idea of the work and their idea of the work fail to match. You cannot get that from a checklist, because a checklist can only ask the questions someone already knew to ask. The whole point of letting the operators in early is that they ask the questions nobody knew to ask, in the only way those questions ever surface, which is by hitting them while trying to do something real.

Which is why the internal team cannot be parachuted in on launch day, and why the single most common version of this mistake is so quietly devastating: the people who will run the store for the next five years are treated as recipients of the migration rather than participants in it. They are trained in the last fortnight, handed the keys at the end, and expected to be fluent in a tool they have operated for thirty-six hours.

On Greycott’s migration the thing that broke this pattern was unglamorous and looked, on the plan, like a small line item: the internal team got staging access in week eight, not week twenty. Owen’s content people and a couple of Priya’s operations staff were given logins and a standing instruction to start doing their real work in the new admin in parallel with the old one—building the actual fall collection in staging, running a few actual wholesale orders through it, reconciling a real week against the real system rather than a sandbox. They were terrible at it in week eight, which was the point. By week ten they had filed the kind of bug report you can only write when you’ve felt the thing go wrong under your own hands: the gift-set inventory decrements the components but not the bundle, and that’s going to oversell us at Christmas. By launch they were not being trained on the system. They were operating it, and had been for months, and launch day was—for once—boring for them, which is the highest praise a launch day can earn.

A small solitary figure working alone at a desk in a large empty room, surrounded by cheerful disorder—spilled papers, a worn eraser—while through a far doorway a crowd waits unseen. — Week eight. Nobody watching. This is what you're paying for.

The contrast is the whole argument. The team that meets the system on launch day spends its first month discovering, live and in front of customers, the things the early team discovered quietly in week ten. The bugs are the same bugs. Only the audience changes.

It would be convenient if cycles meant sprints and we could leave it there. They don’t, quite. The sprint demo is the easy cycle, the one every team already runs—here is the thing we built, does it look right, who has notes. It’s necessary and it’s the least valuable loop in the project, because it asks whether the parts work, and the parts almost always work. The hard cycle is the one between sprints, and it’s the one teams skip when they’re behind, which is precisely when they need it most.

What we mean by the hard cycle is the structured retrospective that isn’t about the work just finished but about the dependencies about to bite. Not did we ship the PDP but the ERP integrator’s spec is due Thursday and if it slips we lose the import window, so what do we do Wednesday. Not status—anticipation, of the kind the previous chapter spent its length arguing for, made into a recurring meeting instead of a personality trait. The reason it’s the hard cycle is that it produces no artifact you can demo and no ticket you can close. It produces, on a good week, the early warning that lets you act while acting is still cheap. The project managers who run it are the ones keeping two timelines—the one everyone agreed to and the one they actually believe—and using the gap between them as the meeting’s only real agenda item.

And above that loop, slower and at a different altitude, there’s a cadence the senior stakeholders need that is not the sprint review and should never be allowed to collapse into one. The sprint review answers are the parts working. The senior cadence answers a different and larger question: is the project still pointed in the right direction. Are we still building the business we said we were building three months ago, or did the business change underneath the plan while everyone was heads-down on metafields. That question can’t be answered by a burndown chart and shouldn’t be asked in a standup. It deserves its own room and its own rhythm, and a stakeholder who only ever sees sprint velocity will answer it wrong, because velocity tells you how fast you’re going and says nothing about whether you’re going somewhere you still want to be.

An Open Letter To Whoever Decided UAT Was The Last Thing.

Dear Sir or Madam or Ghost of Project Plans Past,

We have never met, and yet we know you intimately, because we keep arriving at your projects in month four and finding your handiwork. You are the one who put User Acceptance Testing in the final two weeks of the Gantt chart, after development, after assembly, after the buffer you already spent, in a little box the color of an afterthought. You meant well. UAT goes at the end; the users accept the thing at the end; it is right there in the name.

Here is the thing we wish we could tell you, gently, before you did it. Acceptance is not an event. It is not a gate the users walk through on a Tuesday in the second-to-last week, clipboard in hand, blessing the work. Acceptance is a slow thing that happens to people while they live inside a tool and stop being afraid of it. You cannot schedule it for a fortnight any more than you can schedule getting to know someone for a fortnight. You can put two weeks on the calendar and call it Acceptance, and the users will dutifully click through your checklist, and they will accept nothing, because they have not yet had the small private catastrophe—the order that won’t process, the report that won’t reconcile—that teaches a person what a system actually is.

We are not angry with you. We were you, once, on a launch we’d rather not name. We put UAT at the end because the plan had a shape and that was the shape’s last box. The bill for that decision came in two weeks after launch, in six pieces, and we paid it in front of customers. So this is less a complaint than a note left for the next person holding the pen: move it forward. All of it. Let them in at week eight. Let them be bad at it in front of no one. The acceptance you’re hoping for at the end only exists if you started it near the beginning.

With genuine affection, and a slightly haunted look,

The People Who Show Up In Month Four

There’s a thread running under all of this that the end of the first act named and that keeps surfacing whenever the conversation turns to people rather than code. The hardest part of a migration was never moving the data. It was moving the organization that operates on the data—and an organization does not move because you handed it a finished system. It moves because it spent weeks living inside the new system while the old one was still there to fall back on, making its mistakes in private, building the muscle memory that launch day will demand of it. You cannot expect a team to operate, on day one, a system it has never used. Migrate the assumptions, not just the code: the rows are the easy part, and the people who have to run those rows are the part the plan keeps forgetting to schedule. The earlier they’re in the room—in the actual admin, doing actual work—the smaller the gap between the launch you ship and the launch they can run.

So the chapter’s whole instruction fits on an index card, which is appropriate for a chapter that asked you not to pad it. Run the sequence as a waterfall, because the platform makes you. Run the days as cycles, because the black box always ends in a panic. And let the people who’ll live in the store live in it early, while being bad at it is free.

The migration that opened this chapter had a clean plan and a competent team and a QA phase exactly where the textbook says to put it. Here lies the launch that tested fine and failed for two weeks anyway: the parts all worked, and nobody had ever asked the system to be a store.