create-and-cleanup-migration

Create And Cleanup Migration

Drive a ClawHub Convex migration from implementation through production cleanup,

with explicit operator gates before destructive execution and before removing the

temporary migration code.

When To Use

• A Convex production data migration, backfill, destructive cleanup, schema

narrowing, table reshaping, or one-off maintenance function is needed.

• Temporary Convex code must be created, deployed, run, verified, and then

removed after it is no longer useful.

• The user asks for the full lifecycle: implement migration, PR, deploy, dry run,

apply, verify, cleanup PR, deploy cleanup.

Required Companion Guidance

1. Start with convex-migration-helper.
2. Read convex/_generated/ai/guidelines.md before editing Convex code.
3. Default to @convex-dev/migrations for production data changes.
4. If not using @convex-dev/migrations, write down why the component is

unnecessary and provide equivalent:

• dry-run support
• cursor batching
• resumable/progress behavior
• destructive confirmation token
• real Convex runtime validation

1. Use clawhub-convex for repository-specific file placement and runtime

targeting. Use clawhub-production-release for production deploy phases.

Safety Rules

• Never run a destructive production apply step until after presenting dry-run

results and receiving explicit user confirmation in the current thread.

• Before implementing anything, classify the requested "migration" as one of:

code deploy, existing Convex function run, operator import/export command,

schema narrowing, data cleanup, or cleanup-code removal. Do not invent a new

Convex migration function when the issue or PR specifies an operator command

such as convex import --replace.

• Never remove migration code until after presenting apply/verification results

and receiving explicit user confirmation in the current thread.

• Keep production commands pointed at the explicit deployment name when known;

do not rely on generic --prod if this repo's guidance says to verify the

actual deployment.

• If the migration can affect visibility, moderation, ownership, billing,

installability, or public API output, call that out before the apply gate.

• Preserve resume cursors, run IDs, PR URLs, deploy URLs, and final stats in the

handoff.

Phase 1: Design The Migration

1. Identify the intended data change and whether it is:

• schema widen/migrate/narrow
• field cleanup
• table cleanup
• ownership/relationship repair
• recurring maintenance

1. Choose the implementation:

• Prefer @convex-dev/migrations for non-trivial production data.
• Use a hand-rolled internal function only for a clearly small or special

case, and document the exception.

1. Define done criteria:

• dry-run expected counts
• apply expected counts
• verification query/result proving no remaining targets
• cleanup PR scope

Phase 2: Implement

1. Add or update the Convex migration/maintenance code.
2. Include argument validators for every Convex function.
3. Include dry-run support.
4. Include batching and resume/progress state.
5. Include a confirmation token for destructive writes.
6. Keep apply logic idempotent where practical.
7. Add targeted tests for business logic and safety gates.
8. Add real Convex runtime validation for Convex semantics such as pagination,

validators, internal/public function boundaries, scheduler behavior, and

action/query/mutation interactions.

Phase 3: Local Validation

Run the smallest meaningful set first, then broaden before PR handoff:

• targeted unit tests for the migration logic
• bunx convex codegen when Convex API/schema changed
• bunx tsc --noEmit or the repo's Convex deploy typecheck path
• bun run ci:static
• bun run ci:unit for source/test changes unless explicitly waived
• a real local Convex validation path, such as bunx convex dev --once,

convex run, HTTP smoke, or local-auth Playwright, covering the changed

Convex behavior

If local real Convex validation is blocked, record the blocker and make the PR

or deployment plan explicitly compensate with an equivalent runtime proof.

Phase 4: PR, Review, Merge, Deploy

1. Open a focused PR containing the migration implementation.
2. Include:

• summary
• migration strategy
• dry-run/apply safety gates
• tests and runtime validation
• cleanup plan

1. Run the repo's review/CI workflow required by AGENTS.md.
2. Address actionable review findings.
3. Merge only after required checks are green or the user explicitly accepts a

documented risk.

1. Deploy the relevant production target from main.
2. Wait for deployment success before running the production dry run.

Phase 5: Production Dry Run

1. Run the production dry run with bounded batch settings.
2. Resume until either:

• isDone: true, or
• a clearly documented safety cap is reached.

1. Present results to the user before apply:

• deployment name
• command shape
• dryRun
• isDone
• done/progress fields
• scanned/matched/patched/deleted stats
• sample IDs
• resume cursors if incomplete
• known user-visible or operational implications

1. Stop and wait for explicit user confirmation before applying.

Phase 6: Production Apply

1. Run only after explicit user confirmation of the dry-run results.
2. Use the destructive confirmation token.
3. Resume in bounded batches until complete or until a documented safety cap.
4. Present apply results:

• patched/deleted counts
• skipped/missing counts if tracked
• final cursors/progress
• any errors or partial completion

1. Run verification:

• dry run or status command should show zero remaining targets, or
• explain why remaining targets are expected.

1. Stop and wait for explicit user confirmation before cleanup-code removal.

Phase 7: Cleanup PR

1. Remove temporary migration functions, tests, docs, scripts, and generated API

entries that are no longer needed.

1. Keep durable specs/docs only if they explain lasting behavior or invariants.
2. Run targeted validation plus the repo-required gates for the touched surface.
3. Open a cleanup PR with:

• apply results
• verification proof
• explanation of removed temporary code

1. Merge after checks/review.
2. Deploy the cleanup PR if removing Convex functions or schema/code that affects

production.

Final Handoff

Report:

• implementation PR URL and merge SHA
• production deploy run URL and deployed SHA
• dry-run result
• apply result
• verification result
• cleanup PR URL, merge SHA, and deploy run URL
• any remaining follow-up tasks or intentional retained migration code