Modernization Instructions are detailed project specifications for your migration. They describe exactly how will transform your source code into the destination.
Take the time to review the Modernization Instructions carefully. Once approved, they cannot be edited. If you need changes after approval, you’ll need to start a new migration.
Reviewing Instructions
After you submit your Modernization Goals, automatically generates the Modernization Instructions. To review:
- Click Instructions in the left sidebar
- Read through the generated specification
- Check that it captures your intent
What to Look For
- Target stack — Are the destination technologies correct?
- Migration approach — Does the planned transformation make sense?
- Requirements — Are all your constraints captured?
- Scope — Is it migrating the right parts of your codebase?
Editing Instructions
If something needs adjustment, edit the Instructions directly:
- Click into the editor
- Make your changes
- Click Save Changes
What You Might Edit
- Add missing requirements
- Clarify ambiguous sections
- Specify preferred libraries or patterns
- Adjust the scope of migration
- Add constraints (e.g., “maintain backward compatibility”)
Iterating on Instructions with
After editing, you can click on Auto-review to have compare your changes against the Source Architecture and your original intent. It may suggest:
- Clarifications for ambiguous statements
- Missing details that could cause issues
- Potential conflicts or inconsistencies
For each recommendation, you can Accept or Reject it. You must resolve all recommendations before approving.
Approving Instructions
When you’re satisfied with the Instructions:
- Resolve Auto-review recommendations (if any)
- Click Approve
- Confirm the approval
After approval, immediately begins generating the Destination Architecture and planning your migration roadmap.
What Happens After Approval
The approved Instructions trigger:
- Destination Architecture Generation — designs the target structure
- Roadmap Generation — Milestones are planned based on the Modernization Instructions
You’ll be able to review the Destination Architecture before milestones begin executing. See Destination Architecture for details.
Best Practices
Be Explicit About Preferences
Don’t assume will guess your preferences. If you want:
- A specific testing framework → say so
- A particular folder structure → specify it
- Certain naming conventions → include them
Consider Edge Cases
Think about areas where defaults might not work:
- Configuration files that need special handling
- Environment-specific code
- Integration points with external systems
Review with Your Team
If others will work with the migrated code, consider having them review the Instructions before approval. They may catch requirements you missed.
Troubleshooting
”I approved but now I need changes”
Once approved, Instructions are locked. To make changes:
- Review what’s already been generated (architecture, milestones)
- If early in the process, consider starting a new project with updated goals
- For minor adjustments, use Rules to guide specific behaviors
- For milestone-level changes, see Editing Milestones
”The Auto-review recommendations don’t make sense”
Recommendations are suggestions, not requirements. If a recommendation doesn’t apply to your situation, click Reject and proceed.
”Instructions don’t match my goal”
If the generated Instructions significantly miss your intent:
- Edit the Instructions to correct the misunderstanding
- Use Auto-review to validate your changes
- Approve only when satisfied
