mindspeed-fsdp2-migration-main

MindSpeed FSDP2 Migration Master Control

Objective

Coordinate the complete migration process from the source repository to MindSpeed-MM FSDP2 by scheduling dedicated sub-skills and executing acceptance gates.

Applicable Scenarios

• The user requests migrating a new open-source model to MindSpeed-MM FSDP2.
• The user needs end-to-end migration orchestration covering model, data, configuration, and validation.
• The migration task requires sequential advancement across modules and a unified summary report.

Inapplicable Scenarios

• The task only involves model code adaptation.
• The task only involves dataset adaptation.
• The task only involves YAML/configuration adjustments.
• The task only involves post-implementation validation.

Input

• source_repo_path
• target_repo_path
• model_identity(model name and modality)
• source_entrypoints(training, data, model entry points)
• runtime_assets(real runtime assets, such as model_path、dataset_path, optional image_root）
• constraints(editable paths, core changes prohibited, reuse first)
• acceptance(functional + reliability gates, and a single distributed E2E run passes)

Output

• changeset_manifest
• compatibility_matrix(model/data/configuration mapping)
• verification_evidence
• risk_register
• next_actions

K0 Knowledge Reserve Gate (must be completed before execution)

1. Required reading documents:
   • ../docs/MIGRATION_GUIDE_MINDSPEED_MM_FSDP2.md
   • ../docs/MIGRATION_GUIDE_MINDSPEED_MM_FSDP2_DEVELOPER.md
2. Required directories to scan:
   • MindSpeed-MM/mindspeed_mm/fsdp/models/
   • MindSpeed-MM/mindspeed_mm/fsdp/data/datasets/
   • MindSpeed-MM/examples/fsdp2/
3. Required understanding deliverables:
   • architecture_chain.md(minimal pipeline and key interface mapping)
   • contract_matrix.yaml(model/data/config contract matrix)
   • similar_case_selection.md(most similar cases, reusable points, risk points)
   • preflight_risk_register.yaml(high/medium/low risks and mitigation actions)
4. Stop if not passed:
   • If any deliverable is missing or its content cannot be traced to code/documentation evidence, entering the implementation phase is prohibited

Mandatory Input Validation (must be completed before execution)

1. Path and asset existence:
   • source_repo_path、target_repo_path must exist and be readable
   • runtime_assets.model_path、runtime_assets.dataset_path must exist and be readable
2. Entry point validity:
   • source_entrypoints.train、source_entrypoints.model、source_entrypoints.dataset must exist
3. Editable scope:
   • Changed paths must fall within constraints.editable_paths within
4. Failure if missing:
   • If any validation fails, directly output the failure reason and repair suggestions, and do not enter the implementation phase

Workflow

1. Complete the K0 knowledge reserve gate and deliver understanding deliverables.
2. Discover the source repository and target repository entry points.
3. Build the migration mapping and classify items as "reusable" and "must adapt".
4. Scheduling:
   • mindspeed-fsdp2-model-migration
   • mindspeed-fsdp2-data-migration
   • mindspeed-fsdp2-config-migration
5. Merge deliverables and run mindspeed-fsdp2-verification。
6. If validation fails, route back to the corresponding sub-skill for repair according to ownership.
7. Produce the final migration summary report.

Phased Delivery Contract (to prevent execution deviation)

At the end of each phase, an "inspectable deliverable" must be delivered; otherwise, entering the next phase is prohibited:

1. Discovery phase deliverables:
   • source_target_inventory.yaml
   • entrypoint_checklist.md
2. Mapping phase deliverables:
   • compatibility_matrix.yaml
   • reuse_vs_adapt.md
3. model/data/config phase deliverables:
   • Each sub-skill separately acceptance_checklist.md
   • changeset_manifest.yaml
4. Validation phase deliverables:
   • verification_report.md
   • evidence.json
   • failed_cases.md(only on failure)
5. Summary phase deliverables:
   • migration_report.md
   • risk_register.yaml
   • next_actions.yaml

Failure Attribution and Backflow Rules (must be executed)

• from_pretrained / _from_config / .loss contract issue -> model
• dataset_type / missing field / collate issue -> data
• model_id / dataset_type / training.plugin / strict-extra layering -> config
• When attribution is impossible:
  • First output a minimal reproduction and evidence
  • Then assign handling according to the "first failing gate", and do not attribute vaguely

Prohibited actions

• Do not skip the K0 knowledge preparation gate and implement directly
• Do not start code changes before completing prerequisite validation
• Do not skip any phase deliverable
• Do not claim "passed" without command evidence
• Do not write the cause of failure as "possibly/probably" without providing reproduction evidence
• Do not bypass constraints.editable_paths to modify the core framework

Mandatory rules

• Each sub-skill artifact must follow single-responsibility ownership.
• Do not claim completion without verification evidence.
• Enforce plugin/registration consistency:
  • model.model_id
  • data.dataset_param.dataset_type
  • training.plugin
• Migration changes must be limited to the allowed editable paths.

Exit criteria

• Both the functional gate and the reliability gate pass.
• At least one distributed end-to-end training run succeeds.
• All conclusions in the final report are supported by evidence.

Progressive resources

• checks/orchestration-checklist.md
• checks/knowledge-gates.md
• checks/preflight-gates.md
• checks/phase-delivery-gates.md
• templates/migration-report-template.md
• templates/fsdp2-migration-runbook.md
• templates/fsdp2-migration-quickstart-zh.md
• templates/knowledge-artifacts-template.md
• templates/compatibility-matrix-template.md
• templates/failure-routing-template.md

Read these files only when the current step requires a detailed checklist, Runbook process, Quickstart guide, or report format.

External references (key points of migration technology)

• ../docs/MIGRATION_GUIDE_MINDSPEED_MM_FSDP2.md
• ../docs/MIGRATION_GUIDE_MINDSPEED_MM_FSDP2_DEVELOPER.md