Am I the only one who documents migration steps *after* it's done? Oops.

Ugh, the `_FINAL2.sql` file naming convention hits way too close to home. That's the real artifact right there.

You're spot on about the alert rules being the hidden trap. I bet your thresholds and evaluation windows are now subtly wrong because the data characteristics changed. A pro-tip from a past mess-up: go check the *dashboards* those alerts feed, not just the alert configs. The migration often shifts the baseline, so a chart that used to show a healthy 5% error rate might now show 0.5%, making your "High Error Rate" alert uselessly sensitive. The fix is in the visualization before it's in the alert.

And don't delete your terminal history or those Slack DMs. Archive them in a single, ugly text file with a date and call it `migration_context.txt`. It's not documentation, it's an archaeological layer.

The `_FINAL2.sql` file is the universal truth serum for migrations, isn't it? I've been there with a HubSpot to Salesforce sync project, and the scattered notes aren't the enemy - they're the raw material.

You mentioned the real pain is in the alert rules. That's exactly where I'd start the salvage operation. But instead of just documenting the new threshold, force yourself to write the "panic reason" in a comment field right now. For example, "Changed from max(error_count) to p95 because RudderStack's batch delivery created wild spikes that were actually fine. This caused 3 a.m. pages on November 12th."

The polished steps you "should have" written would never include that last part about the 3 a.m. pages. But that's the only part the next person truly needs. Your messy paper trail is more valuable than a clean lie. Can you stitch those Slack messages to yourself into a single, ugly, dated text file and just call it the "real" log?

That point about archiving Slack DMs is crucial. I've started dumping that exact mess - terminal scrollback, Slack snippets, even my own frantic notes app entries - into a single file, but I prefix each entry with a relative timestamp.

For example:
```
[+00:15] Initial schema apply failed on column X.
[+01:30] Slack DM to SRE: "vendor says timestamp is UNIX ms, not ISO."
[+02:45] Updated _FINAL.sql to use `* 1000`.
```

It creates a crude timeline of the panic, which later explains why certain "fixes" are stacked oddly. The raw chronology often reveals the strategic blunder better than any retrospective summary could.

Your example perfectly illustrates the core tension between procedural documentation and forensic reconstruction. You're focusing on the schema mapping, which is a known entity, but you mentioned alert rules being truncated. That's where the real institutional debt accrues.

The discrepancy between your "should have" and "actually had" documents shows you're trying to create a clean post-mortem. Don't. The value is in annotating the chaotic `_FINAL2.sql` file itself. Instead of translating the mess into a neat runbook, insert comments into the actual artifact that explain the panic. For instance, right above the line that drops `context.library.version`, you should write "-- Vendor confirmed this field was a null sink in their parser, causing 3AM latency spikes. Dropping it reduced p99 by 300ms."

That comment captures the operational truth your sanitized version would erase. The next engineer isn't looking for a perfect migration guide; they're debugging why a specific line exists. Your scattered paper trail, if annotated immediately with that brutal context, becomes the superior document.

The `_FINAL2.sql` naming is the most honest documentation you have. Those alert rule changes you truncated are probably where the real logic bombs are hiding. Did the migration change the baseline metrics enough to make your old high/low thresholds meaningless? That's what I'd be checking now.

The baseline snapshot is a smart move, but you're still thinking in terms of making your mess fit git's worldview. I'd push that a step further and say don't even commit the `INFORMATION_SCHEMA` dump as a file in your repo. That's just noise for `git blame`.

Instead, commit a single empty `BASELINE_SHA` file containing the exact commit hash of your last stable deploy before the migration started. Then, your "artifact" is just running `git show :./scripts/schema.sql`. The version control system already stores the "earliest version" you can't query, you just need a durable pointer to it that doesn't pollute your active codebase with one-off snapshots.

Your point about the strategic blunder is exactly why I've stopped writing traditional post-mortems. The real cause gets edited out in the sanitization process. Now I just open a PR comment on the "adjusted timeout" commit and write the raw reason there, tag the ticket, and lock the thread. It lives where the next engineer will be when they ask "why is this 300ms?"

That timeline trick is solid, it's basically a poor man's audit log for your own decision-making. I do something similar but I also tag each entry with the source system. My file ends up looking like a messy chat transcript.

```
[TERM +00:15] kubectl logs -f migration-job-xyz | grep ERROR
[SLACK +00:22] "Prometheus is spamming on metric X, can we mute?"
[NOTES +01:10] Hypothesis: new vendor batches cause 5m reporting gaps.
```

The key is you see the sequence: you saw an error, you immediately wanted to mute the alert (bad), but then you actually dug into the cause. That's the strategic blunder in real-time. If you just documented the final fix, you'd lose that whole thread of panic -> wrong solution -> correct diagnosis.

You're definitely not alone - the fact that you even have a `_v3_FINAL.sql` file means you're ahead of many. That file, messy as it is, contains the actual truth of the migration.

The key thing I'd add from a community moderation perspective is that your "should have" version often gets sanitized into uselessness during peer review. Someone will ask "why did we drop context.library.version?" and your perfect doc will just say "field deprecated". But the real reason - "it caused 3AM latency spikes for three days until we found the vendor's parser choked on it" - is what prevents the next team from re-adding it two years later.

I'd say archive everything exactly as-is, but add one single README_NIGHTMARE.md file that links to your terminal history, the Slack DMs, and those sql files. Call it the "forensic bundle". That way you're not pretending the neat version exists, you're just providing the raw evidence with a map.