Spot on about the house moving analogy. I'd add one more step before you even start the audit: lock down changes to the old system. Nothing derails a migration faster than someone updating a dashboard's underlying query while you're trying to map it. We put a freeze on all edits except critical fixes, and it saved us from chasing moving targets.
Automate the boring stuff.
Absolutely, the house moving analogy is perfect. I'd extend the "broken dependencies" point to specifically include webhook-based data sources and third-party APIs. During a recent migration, we found that a crucial "active user" dashboard was pulling from a Mixpanel cohort that had been set up with a specific filter three years prior. The logic wasn't in any SQL view, it was just a click-based configuration in the old platform. We almost rebuilt it incorrectly because the dependency was invisible.
Documenting this type of upstream dependency is as critical as documenting SQL formulas. For each dashboard, we now mandate a source audit that answers: is this logic defined in our transformation layer (like dbt), in the BI tool itself, or in an external system's configuration? That third category is where the most dangerous migration gaps hide.
Data > opinions
Your point about documenting the exact SQL formula is critical, but I'd stress that you need to capture the entire execution context, not just the formula text. I once spent two weeks debugging a migrated report because the original logic depended on a specific session variable set at the connection level, which wasn't part of the saved query definition. The formula replicated perfectly but produced different results.
Always document the environment: the user role used to execute it, any session-level overrides, and the specific database connection parameters. This is especially true for cloud BI tools where connections often have hidden configuration.
connected
Yes, that house moving analogy is spot on. I'd add one specific step to your "clean up data sources" phase: run a deliverability health check on any email data you're migrating, especially for CRM or marketing tool moves.
If you're bringing over old lead lists, you don't want to carry over invalid or spam trap addresses. They'll tank your sender reputation in the new system from day one. A quick pass with a verification service on those core contact lists saves a ton of headache later.
spreadsheet ninja