Committee document
Architecture decision record: the migration method
An ADR template for the choice of migration method, filled in with a typical case. Replace the bracketed figures with your own. Below it: how to tell leadership the free tool will not finish.
Status
Status and context
Status: [proposed | accepted], [date]. Context: [the estate, about N objects after dead code] moves from [source] to [target] by [date]. The platform’s free tool has been run; it converted [share] of objects and left [the procedures, SSIS packages and schedules] unconverted, with no per-object evidence.
Decision
Decision
Use the free tool for the SQL it converts well. Convert the remainder with fixed-rule conversion, and reconcile every object, including the free tool’s output, against the original on agreed inputs before cutover.
Options
Options considered
| Option | Why not chosen, or why chosen |
|---|---|
| Free tool only | Leaves [remainder] to hand-fix; no evidence per object |
| Hand rewrite of the remainder | Each engineer rewrites differently; validation becomes most of the project |
| AI assistant for the remainder | Output changes between runs, so it cannot be proven by rerunning |
| Fixed-rule conversion of the remainder | Chosen: same input gives the same output; a report per object; fixed price |
Consequences
Consequences
- Two tools in the pipeline, with one reconciliation standard across both.
- Converted code is native to [target], with no vendor runtime.
- A named engineer approves every change a rule did not make.
- Cutover moves domain by domain against a written threshold.
Telling leadership
How to tell leadership the free tool will not finish
Lead with the count, not the tool. Say what it converted, what it left, and what proving the whole estate needs. Then give the fixed price for the remainder and the date it fits. A sentence that works: “The free tool converted [share]. The [N] objects it left are the procedures and packages finance depends on. Converting and proving them costs [price] and fits before [date].”
Below the document
Where to read next
Print or save this page as the document. Every figure in it is one the reader can check on the linked pages.
FAQ
Frequently asked questions
How do we tell leadership the free migration tool will not finish the job?
Lead with the count: what the tool converted, what it left, and why the remainder matters. Then give a fixed price for the remainder and the date it fits. Leadership hears a plan with a number, not a tool that failed.
What goes in an architecture decision record for a migration?
Status and context, the decision, the options considered with why each was or was not chosen, and the consequences the team accepts.
Last reviewed:
Find out what your logic debt is costing you.
Every object counted, lineage, dead code and a fixed price in three business days. $3,000, credited.
Not sure which door? The scorecard takes ten minutes and tells you.