What I Check First When Debugging RAG Migrations

A RAG model change looks like a configuration update, but it is really a data movement problem between existing documents and a new embedding collection.

Three checks first

• Make sure the current migration status is stored explicitly.
• Do not count deleted and active documents through the same counter.
• Create a retryable intermediate state before applying the result.

The flow I prefer

I avoid inferring state from timestamps and store progress in a form users can inspect. That reduces the chance of data loss when a retry or cleanup step runs.

type MigrationStatus = 'idle' | 'preparing' | 'ready' | 'applying' | 'done' | 'failed';

Good migration code is not just fast code. It can explain where it stopped when it fails.