The CRM Migration playbook.

The audio brief.

One narrator, five minutes, the whole shape of the project — now with the deck that runs alongside it. Play it before you open anything else; it's the fastest way to get into the right mindset for a migration. In a hurry? Change the speed under the deck — it sticks next time.

Four phases, one motion.

Every migration moves through the same four phases. The weight sits in phase one — get the Blueprint right and the other three go smoothly.

Which mode are we playing on?

Before a single object moves, settle one question: what kind of migration is this? It sets the whole plan — the discovery depth, the timeline, and what you show up recommending. There are three modes. Name it out loud with the customer up front.

Kick off a migration in one paste.

Don't dig through the GitHub repo. Copy this prompt, drop in the customer name, and send it to your Claude. It clones the template, reads the AGENTS.md, and walks the scoping checklist with you.

The hard part isn't the data. It's alignment.

The mechanics of a migration are knowable. The esoteric part — the thing that quietly sinks projects — is stakeholder alignment: getting everyone to agree on how the system behaves in the new world. That's where the hours go, so run the Blueprint to collapse that, not feed it.

Inventory every tool. None of them "just reconnect."

Every integrated tool is its own mini-project — not a checkbox. Gainsight, HubSpot, Apollo all told us the rehook-up was easy, "a couple hours." Every single one had errors and nuances that drew it out for weeks.

Which components need a specialist.

The single biggest root cause of a bad migration is the wrong personnel on a specialized component. A generalist can't scope what they've never built — they don't know what they don't know. In the Blueprint, name the components that need a specialist and staff them.

Talk to every department — not just the obvious three.

Entire functions surfaced mid-project that were never in scope. Sales, marketing, and CS are the easy ones to remember. It's the others that bite.

Duplicates come in three flavors — map the strategy for each.

The Blueprint Review — one artifact to get the green light.

This is what you show up with. Not a questionnaire — a compare-and-contrast map: everything they have today on the left, exactly what it becomes on the right, and the handful of things that won't come over flagged in red. Tabs for the optimization layers (lifecycle, attribution) show current → recommended → mapped, with names they can tweak. They poke holes in this — and that's the green light.

The field map is a data deliverable — a hard gate.

Sic Claude on the audit — but know its limits.

Claude is the right tool for the field-by-field audit and the bulk build. But there's one trap that makes a build look perfect while it's silently broken.

Migrate in pieces — not everything at once.

Doing everything at once is why MediaFly slipped: things broke slowly, then it was one person after another saying "we don't have this, we don't have that." Split the migration by object and move in order.

Don't burn the API when a change set will do.

On cutover, an engineer ran out of API credits mid-push, called Salesforce for emergency capacity, and got capped at a million. Most of that API load was unnecessary.

Greenfield goes straight to prod. A merger needs a sandbox.

The build environment is decided by the mode. Don't over-engineer a greenfield build with a sandbox it doesn't need — and don't ever touch a live merged org without one.

Stakeholders first. Reps last. Always.

A concrete checklist for every kind of thing.

QA-ing a fresh instance is a huge one. Don't wing it — give each component a checklist so the coverage is provable.

Overlap the two systems. Don't detonate the old one.

The safest cutover isn't a switch-flip — it's an overlap. The new instance is fully built; the team keeps working in the old one; you run both in tandem and compare outputs before anyone depends on the new world. Aim for a month. You can do it in less, but a month gives the weird timing room to surface — things that only fire once a week or once a month need a full cycle to prove out.

Cutover Friday. Run it like a blackout.

Enablement is what kills the maintenance tail.

The more completely you enable, the less ad-hoc cleanup you're doing for months afterward — the boring maintenance that quietly eats a project. Over-invest here on purpose. Do it in layers.

Quote it post-Blueprint — and bake in fix time.

The Blueprint is the big variable and the part you can't control, so frame every estimate post-Blueprint. With a green check on the Blueprint, a clean migration runs roughly:

Base migration, then add the specialized work.

Price the base migration on its own, then stack the specialized workstreams on top. Fortune-500-scale runs longer.

Two platforms, three directions.

The method above is the same every time. What changes is what you gain and lose based on where you're coming from and where you're going. Read this before you scope.

What you'll lose — and what it quietly costs.

The other two directions rarely surprise you. This one does — it's the direction with real casualties, and several of them show up as line items on a bill. Scope every one and tell the customer plainly what won't come over.

Architecture replicates. Discovery goes to the edges.

Almost everything in HubSpot has a cleaner Salesforce equivalent — contacts, companies, deals, reporting all map straight across. So don't burn discovery on the core object model. Spend it on the edges.