1# Workflow Details
2 
3## Status Tracking
4 
5Maintain a `migration-status.md` file in the output directory (`<workspace-root-basename>-azure/`):
6 
7```markdown
8# Migration Status
9| Phase | Status | Notes |
10|-------|--------|-------|
11| Assessment | ⬜ Not Started | |
12| Code Migration | ⬜ Not Started | |
13```
14 
15Update status: ⬜ Not Started → 🔄 In Progress → ✅ Complete → ❌ Failed
16 
17## User Progress Updates
18 
19During long-running operations (Azure deployments, image pushes, environment provisioning), **proactively report progress** so the user is never left waiting without feedback:
20 
211. **Resource-level status table** — After submitting a deployment, poll `az resource list` or `az deployment operation group list` and present a status table:
22   ```
23   | Resource | Status |
24   |----------|--------|
25   | VNet     | ✅ Created |
26   | ACR      | ✅ Created |
27   | Container Apps Env | 🔄 Provisioning |
28   | order-service | ⬜ Waiting |
29   ```
302. **Explain what's slow** — If a resource takes >2 minutes (e.g., Container Apps Environment with VNet), tell the user *why* ("VNet integration provisions internal load balancers and DNS — this typically takes 3-5 min").
313. **Don't go silent** — If a single `az deployment group create` covers all resources, poll `az resource list -g <rg>` periodically and update the user on newly created resources.
324. **Announce each phase transition** — When moving between skill phases (assess → migrate → deploy → validate), clearly tell the user what just completed and what's next.
33 
34## Error Handling
35 
36| Error | Cause | Remediation |
37|-------|-------|-------------|
38| Unsupported runtime | Source runtime not available in target Azure service | Check target service's supported languages documentation |
39| Missing service mapping | Source service has no direct Azure equivalent | Use closest Azure alternative, document in assessment |
40| Code migration failure | Incompatible patterns or dependencies | Review scenario-specific guide in [lambda-to-functions.md](services/functions/lambda-to-functions.md) |
41| `azd init` refuses non-empty directory | azd requires clean directory for template init | Use temp directory approach: init in empty dir, copy files back |
42 
43> For scenario-specific errors (e.g., Azure Functions binding issues, trigger configuration), see the error table in the corresponding scenario reference.
44