MIGRATION PLAN
What to agree before the first edit
Before the first edit, the team maps every status-write site and transaction boundary, then records compatibility, rollout stages, checks, and rollback in the plan.
Map the system first
The team is moving order status updates from direct writes to a transactional outbox. The change touches 50+ write sites while the old and new processing paths must coexist.
lesson goalRecognize when planning mode must come before the first edit: map dependencies and agree on a safe change sequence.
12 minutes
What to change is clear. The order is not.
This is an end-to-end change: HTTP handlers, background jobs, and retries are connected, while an immediate status update becomes asynchronous event processing.
How should the migration begin?
The old and new processing paths must run in parallel; the system cannot stop.
What must the team do before the first edit?
Not the safest step: tests reveal dependencies too late
Failing tests reveal only dependencies that already have coverage, and only after an edit. The safe sequence is dependency map → migration plan → code → verification.
Correct: map first, then plan
The team maps every write site and dependency, then records compatibility conditions, rollout stages, checks, and rollback. The plan must be agreed before the first edit.
Not the safest step: folders do not reflect the process
Folder boundaries do not match the business process, so subagents may choose incompatible solutions. Split the work only after the team agrees on one plan and migration rules.
Not the safest step: it is too early to automate
A template speeds up only a well-understood, repeatable operation. Agree on the migration stages first, then automate stable steps.
Map dependencies and plan first. Then edit code.
Choose the correct answer or reveal it to see the comparison.
OUTCOME
Controlled migration
The map covers every status-write site. The migration has four verifiable stages, each with compatibility conditions and a rollback path.
Every stage has clear boundaries, monitoring, and rollback. Code changes begin after the plan is agreed.
- 01 · inventory HTTP, jobs, retries, and monitoring
- 02 · place the outbox behind a feature flag
- 03 · connect consumers with observability
- 04 · switch the source of truth with verified rollback
When to use planning mode
To mark this lesson complete, choose the correct answer or reveal it.
source: Lecture 01 — Moving order processing to events