The Migration Looked Complete
Jekyll to Astro, 45 pages, build passing. If you generate code with AI, you already know the shape of this: the thing that compiles is not the thing that works. A rebuild nobody audited is not a migration — it is a moving accident.
The site merged from Jekyll to Astro. The build passed. The pages rendered. And buried inside the output were the failures that only an audit could surface: a broken JavaScript redirect, article SEO metadata silently dropped, truncated links, dead references, and icons that had stopped existing.
A green build is the start of verification, not the end of it. The build compiles the code; the audit verifies the product.
What the Move Actually Broke
Every migration needs a second pass. Here is what the second pass found.
The audit went page by page, line by line: HTML structure, components, typography, icons, content structure, CTAs, and the design-system compliance of every element. The goal was not just to fix pages — it was to find the classes of damage a migration causes.
Broken JS redirect A template literal that never resolved — the page that was supposed to redirect simply did nothing.
Silent SEO loss Article metadata — ogType, publishedTime, modifiedTime, tags — was dropped because the layout did not forward it.
Truncated links Three articles had anchor tags cut mid-attribute, replaced with broken prose.
Dead references
Seven broken /scripts/ references and one broken /styles/ reference left over from the old stack.
Nothing in a migration breaks loudly. Everything breaks quietly. The audit is what turns quiet failure into an actual list.
Migrate fast, audit slower. The second pass is where the product is saved.
Audit the Architecture, Not Just the Pages
The page fixes were the surface. The real work was the config-driven cleanup underneath.
A second, deeper audit looked at the whole codebase: architecture, dead code, hardcoded values, dependencies, and docs. The mandate was zero hardcoding and a lean, fast stack. What it found was a Jekyll-era skeleton still wearing Astro clothes.
The pattern is the lesson: a migration that only changes the framework keeps the bad habits. Moving from Jekyll to Astro was meaningless unless the codebase was rebuilt to Astro standards — typed, config-driven, and free of the old stack artifacts.
A framework migration that does not also clean the architecture just moves the mess to a faster compiler.
Audits Are the Quality Gate
This is the same gate logic that runs inside SpielOS: before anything advances — code, content, an agent run — it passes inspection.
The migration audit is evaluation in the oldest sense: a gate between a broken state and a working one. It is the mechanical gate that the content engine applies to drafts — hard rules, no negotiation, pass or fail.
The content pipeline applies the same thinking to writing. The migration applies it to infrastructure. The harness applies it to agents. In every case the shape is identical: generation is cheap, verification is the product.
If you generate code with AI, this is the lesson: the build compiles what you asked for, the audit verifies what you actually needed. Skip the verification and you advance bugs.
Whether it is code or content, the pattern is the same: build, then verify, then advance. Skip the verification and you advance bugs.
Audit Everything You Generate
The checks that caught this class of bug are the same checks you should run on anything AI produces.
Verify the silent metadata. Open the built HTML and confirm SEO tags, redirects, and structured data survived. The compiler does not care about your og:image.
Grep for the old stack. Search for old paths, old class names, old icon libraries. The old stack leaves fingerprints; delete them.
Move every hardcoded value to config. If a URL, key, or name appears more than once, it belongs in a config module. Migration is the best excuse to centralize.
A migration is complete when the audit passes, not when the build does.
The build said 45 pages, zero errors. The audit found the errors the build could not see.
Broken redirects, dropped metadata, dead references, hardcoded keys. Verification is the product; generation is just the first draft.
Read about the gates