The medieval account of moving a relic was legitimacy work, written long after the move. The engineering migration retrospective is the same document, and it fails the same way.
In the year 828, two Venetian merchants named Buono da Malamocco and Rustico da Torcello smuggled the bones of Saint Mark the Evangelist out of Alexandria by packing them in a barrel under layers of pork. The story has it that the Muslim customs inspectors lifted the lid, recoiled at the unclean meat (Kanzir!, pig!), and waved the cargo through without digging deeper. The relics reached Venice. The city raised a basilica over them, took Mark as its patron, and made his winged lion the emblem it still flies today.
Now here is the detail that should interest anyone who has ever written, or read, a migration post-mortem. The detailed account of that theft, the Translatio Sancti Marci, the text that names who carried the bones, explains why the taking was righteous, and records the miracles that confirmed the saint's arrival, was not written in 828. By the best datings it was composed decades later, and by some, well over a century after the fact. The document that justified the relocation arrived generations after the relocation itself. It was never a record of the move. It was legitimacy work, done long afterward, by a community that needed to prove the bones it now held were truly, rightfully, Mark's.
That document belongs to a genre. From roughly the 8th through the 12th centuries, the translatio was a recognized sub-genre of saints' lives: the formal account of moving a relic from one shrine to another. The genre exists for a precise reason. Moving relics is structurally contested. The originating shrine has standing to object, and the destination needs ratification that the physical act of carrying the bones cannot, by itself, supply. And once you learn to read a translatio, you begin to see the same document everywhere a contested relocation needs justifying, including, unmistakably, in the engineering blog post that announces a code migration. The migration retrospective is a translatio. It succeeds or fails on exactly the two conditions a relic-translation did.
A translatio is not reportage. It is, in the words of the scholarship, an act of appropriation that requires justification: you cannot simply relocate holy relics and say nothing. The taking has to be made righteous after the fact, and the Translatio Sancti Marci made it righteous with two claims, neither of which is a physical fact about a barrel of bones.
The first was rescue: the caliph in Alexandria was said to be about to dismantle the shrine, so the merchants were not thieves but saviors, spiriting the saint away from desecration. The second was destiny: Venice was predestined to be Mark's resting place, and there was even a legend that an angel had once told Mark his body would rest in the lagoon. The move wasn't a theft; it was the fulfillment of a plan that had always been in motion. Rescue and destiny: we saved it, and it was always meant to come to us.
And the translatio succeeded on two conditions. First, the origin could not reclaim. Alexandria, under a different rule and a weakened church, had no power to demand the bones back. Second, and decisively, the relics kept working miracles at the new site, which was the only proof anyone accepted that the saint had genuinely come and was content to stay. The genre was candid enough about the larceny to give it a name: furtum sacrum, "sacred theft," the theft is holy precisely because the saint wanted to be taken. (The canonical modern study of this whole strange business is Patrick Geary's Furta Sacra; the mechanism I'm describing, legitimacy established through narrative and confirmed by miracle, is the consensus of the translatio scholarship.)
Hold those two framings and two conditions in mind, because they are about to reappear in a Markdown file on someone's engineering blog.
Read a migration write-up the way a medievalist reads a translatio and the genre leaps off the page. "We rewrote our entire backend and kept the soul of the system." The founder's-vision retrospective. The "lessons from our great migration" essay that compresses eighteen months of trauma into a clean origin story. These are not, whatever their authors believe, engineering reports. They are legitimacy claims for a contested relocation, and they reach, helplessly, for the very same two framings.
There is always a rescue: the legacy system was about to collapse, was unmaintainable, was holding us back, was a ticking liability. We did not abandon it; we saved the mission from it. And there is always a destiny: this rewrite was always the plan, the old architecture could never have scaled, we were always going to end up on the new stack. Not a gamble, a fulfillment.
And what, exactly, are the relics being translated? Joel Spolsky named them in 2000, in plain engineering language, in what remains the most famous warning against rewrites ever written. The crufty, ugly old code, he argued, embeds hard-earned knowledge about corner cases and bugs. Every gnarled line is a fix for a real problem some real user hit, a bug report paid for in production pain. To throw it all out and start clean is to discard accumulated, hard-won wisdom, to mistake the scar tissue for the wound. Spolsky called rewriting from scratch "the single worst strategic mistake" a software company can make, and pointed at Netscape, which let roughly three years pass between Navigator 4.0 and the ground-up 6.0 rewrite while its market share was eaten alive. That is a translatio that failed: the bones were moved, but the miracles stopped, and the faithful went to Internet Explorer.
I should be honest that Spolsky's rule is canonical, not gospel. Rewrites do sometimes succeed. Herb Caudill's well-known survey of six rewrite stories includes real triumphs alongside the disasters. But that doesn't weaken the frame; it is the frame. Some cult relocations take and some do not, and the entire value of reading these documents as translatio is that it tells you how to know the difference.
Here is the payoff, and it is a genuinely useful tell you can apply this afternoon.
A contested translatio, one whose legitimacy is still unresolved, reads like hagiography. It leans hard on rescue and destiny. It invokes the founder's vision. It narrates the migration as a heroic origin myth. It insists, repeatedly, that "we kept the soul of the system." It reads that way for one reason: because it is still arguing. A community confident in its own legitimacy does not write a saint's life. It writes a procedure manual.
An accepted translatio, the resolved one, reads like a boring engineering report. Here is what we moved. Here was the rollback plan we didn't need. Here is the p99 latency before and after. No miracles are asserted, because miracles are visibly, unremarkably occurring: the new system ships, it scales, the users followed without being argued into it. When the saint is plainly working wonders, nobody has to write three thousand words insisting that he is.
So the diagnostic, stated plainly: if your migration write-up reads like a translatio, your cult relocation has not been ratified yet. The presence of legitimacy work is evidence the legitimacy is still in question. If it reads like a routine report, the question already settled. And the best use of this is on your own retrospective, before you publish it: if you catch yourself reaching for rescue and destiny and the soul of the system, you have learned something the latency graphs won't tell you, that you finished moving the code, but you have not yet finished the migration.
The genre even predicts a specific failure. Fred Brooks named it in 1975: the Second-System Effect. The second system a designer builds, freed at last from the cramped constraints of the first, tends to be over-designed, gold-plated, stuffed with every feature the team ever wished for, until it groans under its own ambition and ships late or not at all. In translatio terms, that is the new shrine claiming more legitimacy than it has yet earned: raising a cathedral before the relics have worked a single miracle, proclaiming the saint's full glory before the saint has even settled in. The over-claim is itself a symptom of insecurity. A genuinely accepted relocation is modest, because it has nothing left to prove.
So how do you run a translatio that actually takes, one that never needs the century-late legitimacy document? Martin Fowler named the pattern, and, too perfectly to leave out, he named it after a tree.
The strangler fig germinates high in the canopy and grows downward, wrapping itself around its host tree, slowly enveloping the trunk, taking over the host's place in the light, until the original dies and the fig is left standing exactly where it stood, having replaced it not in a single violent act but by incrementally proving, branch by branch, that it could do the host's job. Fowler's Strangler Fig migration does precisely this: you build the new system around the old one, route function after function through the new path, and decommission the old only once the new has demonstrably taken over each piece.
That is acceptance by construction. Where the big-bang rewrite asserts a one-time legitimacy and stakes the whole faith on a single cutover (the contested translatio, with its single point of failure and its need for an after-the-fact apologia), the strangler fig earns acceptance by working one small miracle after another, in public, before anyone has to trust it with everything. It never produces a legitimacy document because it never has a contested moment; the bones prove themselves one relic at a time. (And savor the irony in the name: the strangler fig is a predator that replaces its host. The safest migration pattern we have is the predation lifecycle, domesticated and made gentle.)
Which leaves the deepest rule, and the one most migrations get wrong. A relic-translation that moved the bones but not the cult, the feast days, the prayers, the particular way that community had learned to venerate its saint, would end up with a basilica, a body, and no living faith around it. A reliquary, not a religion.
Code is the same. What made the old system work was never only the code. It was the practice around it: the runbooks, the on-call instincts, the tribal knowledge of which alert means trouble and which is noise, the tacit corner-case wisdom that is exactly what Spolsky meant by knowledge "embedded" in crufty code. Migrate the data and the code but leave the practice behind, and you have moved the bones without the cult. And the genre makes a prediction here, a diagnostic heuristic, not a measured statistic, but a reliable one: within roughly a year, the new community will reproduce, one by one, the very complaints the old community had. The same incidents, rediscovered the hard way. The same corner cases, re-hit. The same baffled "why does it do that?", because the knowledge of why never made the trip.
So, whether you are planning a migration or grading one that already happened, three moves follow:
The Venetians spent the better part of a century composing the document that proved Saint Mark had truly come to rest in their lagoon. If your migration needs that document, if you find yourself writing the saint's life instead of the procedure manual, then the bones have arrived but the cult has not, and somewhere in the next twelve months the old system's ghosts will start knocking. Translate the practice along with the code, and you will never have to write the translatio at all.
The translation of Saint Mark's relics, the Venetian merchants Buono da Malamocco and Rustico da Torcello removing the relics from Alexandria to Venice in 827–828, the legend of smuggling the body past Muslim inspectors under pork, and Mark's adoption as Venice's patron (the winged lion), per standard accounts (Saint Mark's relics, Wikipedia; History Walks Venice, "Translatio Marci Evangelistae"). The key honesty point on dating: the act is dated 827–828, but the Translatio Sancti Marci text was composed substantially later (datings range from the 9th century to the late 11th), so the legitimacy narrative postdates the relocation by decades to over a century; the retroactivity is the essay's hook, not an error. The translatio as a legitimacy genre, "you cannot simply relocate holy relics… and say nothing," justified by rescue and destiny framings and functioning to affirm the receiving community's authority, from the relic-translation scholarship (e.g., medievalworlds.net, "Relic Translations and the Affirmation of Authority"); the term furtum sacrum ("sacred theft") and the canonical modern study, Patrick Geary, Furta Sacra: Thefts of Relics in the Central Middle Ages (cited as the canonical study of the genre; specific theses not attributed beyond the consensus legitimacy-by-narrative-and-miracle mechanism). Code-side anchors: Joel Spolsky, "Things You Should Never Do, Part I" (joelonsoftware.com, 2000), rewriting from scratch as "the single worst strategic mistake," old code as embedding hard-won knowledge of corner cases and bugs, and the Netscape 4.0→6.0 rewrite as the cautionary case, presented as the influential-but-contested canonical text, with the counter-cases noted (Herb Caudill, "Lessons from 6 software rewrite stories," which documents successful rewrites). The Second-System Effect: Fred Brooks, The Mythical Man-Month (1975). The Strangler Fig migration pattern: Martin Fowler (via Microsoft Azure Architecture Center and AWS Prescriptive Guidance), including the strangler-fig botany (a plant that envelops and replaces its host). The "code migration retrospective in the wild" genre, e.g. DoltHub's "The Long, Dark Rewrite of the Soul." The "complaints reappear within ~a year" claim is explicitly a diagnostic heuristic, not a measured statistic. The synthesis, the migration retrospective as a translatio, the rescue/destiny tells, the reads-like-hagiography-means-legitimacy-unresolved diagnostic, the strangler fig as acceptance-by-construction, and "translate the cult, not just the bones," is the essay's own argument.
A translatio is a record of who carried the bones, and why. Migrations need the same record.
The reason a migration retrospective turns into a saint's life is that the record of what moved and why was never kept as it happened, so it has to be reconstructed, and argued for, after the fact. chain-of-consciousness keeps that record as the work happens: each agent's reasoning and actions written down as a checkable trail, so "what did we carry across, and why" is a fact you can read back, not a legitimacy document you compose a year later.
pip install chain-of-consciousness · npm install chain-of-consciousness
Hosted Chain-of-Consciousness → · vibeagentmaking.com