02 Plan and design

Facilitator companion to the learner lesson 02 Plan and design.

Timing

About 90 minutes, and almost none of it is unattended. This is the one module built around individual or paired worksheet work, not scripts running in the background. Step 1 (the profiling script) is the only automated piece and finishes in a few minutes; everything else — Step 2's five worksheets and Step 3's migration-plan.md — is where the 90 minutes actually goes. Do not plan a break inside this module; if the room needs one, take it at the boundary with module 03, not partway through the worksheets.

Talk track

• Lead with what this module is not: it is not a delay before the "real" migration in module 03. The most common reason ClickHouse migrations underperform is an architecture problem, not a tuning problem — teams move data first and design later.
• Name this directly, because it is the strongest available argument for spending the 90 minutes: this is the module partners are most tempted to skip, since module 03's setup.sh only warns on a missing or incomplete migration-plan.md — it never blocks.
• Walk through what happens if a partner skips it anyway: they will still succeed mechanically in module 03 — fact_trips still comes up as ReplacingMergeTree, the data still moves — but they will not know why that engine and not plain MergeTree, will not know how the ORDER BY key was derived from the query workload, will not recognize delete_insert and FINAL in the dbt configs, and will not be able to explain or reproduce module 05's benchmark speedups for a customer.
• Point at the Worked Example reference page only after partners have attempted their own plan — it is a sanity check, not a template to copy from before thinking it through.

Common failures

• ACCOUNT_USAGE is unavailable when Step 1's profiling script runs. It needs either a 1-3 hour propagation delay after the Snowflake account was created, or the ACCOUNTADMIN role. The script falls back to INFORMATION_SCHEMA automatically and notes what it could not measure — this is a graceful degradation, not a crash, but a partner may not notice the fallback happened. Point them at scripts/02_query_history.sql, runnable by hand in the Snowflake UI, if the automated profile looks thin.
• A partner treats the Completion Checklist in migration-plan.md as optional. It is not — module 03's setup.sh reads it, and an unchecked box is the signal that this module was skipped in substance even if the file itself exists.
• TODO: no Troubleshooting section exists in this module's own README, unlike modules 01 and 03. Fill this in from rehearsal once the worksheet portion has been run with a live room.

Reset steps

• profile_report.md (Step 1's output) is gitignored and regenerates fresh from the partner's own live Snowflake account on every run — if it looks stale or wrong, just re-run ./scripts/01_profile_snowflake.sh. Nothing to tear down.
• The five worksheets and migration-plan.md are edited in place in the repo — this module provisions nothing in either cloud, so there is no teardown.sh and no setup flags to reach for.
• TODO: this module's README has no Troubleshooting section and no reset tooling of its own, unlike modules 01 and 03-05. If rehearsal turns up a common way partners get a worksheet into a bad state, capture the recovery here.