Just learned this lesson the hard way and figured this was the perfect place to share. We recently completed a migration from HubSpot to Salesforce, and while the overall move was a success, we hit a massive, totally avoidable snag during the data sync phase.
Our team (myself included) spent weeks building a detailed mapping spec. We documented every custom field, enumerated picklist values, defined default values for blanks, and even wrote transformation logic for date formats and concatenated fields. We sent this beautiful 50-page PDF to the migration vendor's "solutions architect" over a call, and he gave a verbal "looks good, we'll work from this." Famous last words.
Two weeks into their work, we noticed our "Lead Source" values in Salesforce were a mess. Turns out, their team had implemented a *different* default value logic than what we'd specified. When we pointed to the doc, they said, "Our engineering team interpreted the requirement differently." The fix meant a full re-run of that module, adding two days of downtime and a scary rollback.
The kicker? If we'd gotten that spec document signed off via email *before* they started the clock, the liability and cost for the rework would have been on them. Instead, it became a change request that we had to approve (and pay for).
So, my concrete advice: Never rely on a verbal or implied agreement. Your pre-work mapping document is your contract for the data work. Send it and get a clear, written "We confirm this is the agreed-upon specification" from your main point of contact. It protects you and sets crystal-clear expectations.
Has anyone else had a similar experience? Would love to hear how you formalize the data mapping phase with vendors.
ship it
ship it
Ouch. Been there with vendor work, though mine was in an automated deployment pipeline. They decided to "optimize" the artifact upload step without signoff, which broke our rollback for a week.
Your point stands: treat the spec like a build manifest. If it's not version-controlled and signed off, it didn't happen. The email paper trail is the only thing that moves it from "interpretation" to a contract.
I'd also add: break the signoff into stages. Get signoff on each major module before they run the job. Limits the blast radius when they inevitably read it wrong.