Setting the file. One moment.
Subchapter 27.58
references/shared/migration-complexity.mdMarkdown13 KBView on GitHub
Shared classification loaded by generate-billing.md and generate-infra.md to right-size migration timelines. The AI path (generate-ai.md) self-sizes from workload profiles and does not use this file.
Collect these values from prior-phase artifacts before classifying:
| Input | Source Artifact | Key |
|---|---|---|
| Service count | aws-design-billing.json or aws-design.json | metadata.total_services |
| Monthly spend | billing-profile.json or estimation-infra.json | summary.total_monthly_spend or current_costs.gcp_monthly |
| Has databases | Design artifact services[] | aws_service in {RDS, Aurora, DynamoDB, ElastiCache, DocumentDB, MemoryDB, OpenSearch} |
| Has stateful storage | Design artifact services[] | aws_service in {EFS, FSx, S3} with replication or versioning hints in sku_hints |
| Has AI workloads | estimation-ai.json exists | File presence |
| Availability | preferences.json | design_constraints.availability |
| Compliance | preferences.json | design_constraints.compliance |
| Multi-region | Design artifact services[] | More than one distinct aws_config.region value |
Evaluate from Large down to Small. The first tier whose condition matches is the result (highest-matching-tier wins).
ANY of the following:
compliance is not empty/none)AI isolation rule: AI coexistence alone NEVER raises the infrastructure
tier. generate-ai.md independently sizes AI integration/evaluation effort,
and that work commonly runs in parallel with infrastructure. Count only
infrastructure complexity here; otherwise a one-service app with one model is
incorrectly classified Large and its effort is double-counted.
NOT Large, and ANY of the following:
multi-azNOT Large, NOT Medium. Equivalently, ALL of:
single-az or unspecifiedTier classification, stage structure, and duration drivers are planning heuristics derived from stack-shape thresholds — not calibrated to observed migrations. Do NOT emit week counts or engineering-hour figures from this file into any artifact or user-facing output. Time is communicated three ways only: stage sequence (ordinal — real information), duration drivers (what makes THIS stack take longer), and operational time policies (watch periods, observation windows — policy choices, kept as-is). Always record tier_bound_by — the single input that bound the tier (e.g. "compliance present", "service_count >= 9") — so readers can see why the tier is what it is.
| Tier | Approach | Duration drivers to name (adapt to stack) |
|---|---|---|
| Small | compressed | Few services, no databases — discovery and provisioning overlap; cutover in one maintenance window |
| Medium | standard_with_discovery | Billing-only discovery gap (configs must be audited), database migration, parallel-run stage |
| Large | conservative_with_discovery | Extended discovery (no IaC), full parallel run, multi-region or compliance baseline, AI track when present |
| Tier | Approach | Duration drivers to name (adapt to stack) |
|---|---|---|
| Small | compressed | Shallow dependency graph, no data-migration stage — smoke-test PoC, single cutover window |
| Medium | phased_cluster_migration | Cluster-by-cluster deployment in dependency order, data migration, parallel-run validation |
| Large | phased_cluster_migration | Additional clusters and cross-cluster networking, large data volumes / replication topology, extended parallel run |
Duration drivers are the honest replacement for hour/week estimates. Name only
drivers that apply to THIS stack, and exclude calendar-only waiting,
observation windows, and parallel AI work already covered by generate-ai.md.
tier_bound_by), then at most 2–3 secondary drivers.N/A — API enablement and Deferred — specialist engagement rows
from service_count; they do not represent implementation work in this plan
(deferred services may still be named as a driver when their specialist
track gates cutover).No parallel-run stage. Discovery and provisioning overlap. Cutover uses maintenance window.
Shortened parallel run. Discovery is an abbreviated audit, not the extended Large-tier discovery.
Full conservative plan. Extended discovery, full parallel run.
Compressed setup. PoC is a 2-day smoke test, not a 2-week phase. No data migration stage (small tier excludes databases by definition).
preferences.json strategyStandard phased plan. Same as the existing generate-infra.md default stages. Apply the existing data-migration skip rule: if no databases/storage, drop the data-migration stage and note its absence as a driver; Cutover and Validation move up in sequence.
Extended infrastructure deployment. Extra time for complex dependency graphs, multi-cluster orchestration, and extended parallel validation.
Risk probabilities should be adjusted based on complexity tier:
| Risk Category | Small | Medium | Large |
|---|---|---|---|
| Incorrect service sizing | low | medium | high |
| Missing dependencies | low | medium | high |
| Data migration complexity | n/a (no DB) | medium | high |
| Cost overrun | low | medium | high |
| Performance regression | low | medium | medium |
| Timeline overrun | low | medium | high |
| Unmapped services block progress | low | medium | medium |
Tighter thresholds for simpler migrations (fewer unknowns, less variance).
| Criteria | Small | Medium | Large |
|---|---|---|---|
| Performance within baseline | Within 15% of GCP | Within 20% of GCP | Within 20% of GCP |
| Monitoring stability | 24-hour watch period | 48-hour watch period | 48-hour watch period |
| Post-migration stability | 14-day observation | 30-day observation | 45-day observation |
| Cost variance | Within 25% of mid estimate | Within 30% of mid estimate | Within 40% of mid estimate |
| Data integrity | 100% | 100% | 100% |
| Service availability | 99% | 99% | 99% |
| Criteria | Small | Medium | Large |
|---|---|---|---|
| Performance within baseline | Within 10% of GCP | Within 10% of GCP | Within 10% of GCP |
| Monitoring stability | 24-hour watch period | 24-hour watch period | 48-hour watch period |
| Post-migration stability | 14-day observation | 30-day observation | 30-day observation |
| Cost variance | Within 10% of mid estimate | Within 15% of mid estimate | Within 15% of mid estimate |
| Data integrity | 100% | 100% | 100% |
| Service availability | 99.9% | 99.9% | 99.9% |
After classification, the consuming generate file must include a complexity_tier field in its output JSON:
{
"complexity_tier": "small",
"complexity_inputs": {
"service_count": 2,
"monthly_spend": 75.71,
"has_databases": false,
"has_stateful_storage": false,
"has_ai_workloads": false,
"availability": "single-az",
"compliance": "none",
"multi_region": false
}
}These fields go at the top level of the generation JSON (alongside phase, generation_source, etc.).