---
id: generate-migration-strategy
agent: ux-design-expert
title: Gerar estratégia de migração em fases para o design system
inputs: [shock report, padrões consolidados, design tokens]
outputs: [estratégia de migração faseada, 'docs/stories/{story}/migration-strategy.md']
elicit: false
modes: [interactive, yolo]
---

# Gerar estratégia de migração em fases para o design system

**Objetivo:** transformar o caos medido e os tokens extraídos num plano de migração em fases — qual
componente migra antes, com que risco, em que ordem — para que a app adote o design system sem
parar de funcionar. Comece simples, refine com feedback.

**Pré-condições:**
- O shock report (`generate-shock-report`) já mostrou o estrago e o ROI por cluster. Sem ele,
  **pare**: migração sem prioridade medida é chute.
- Os design tokens (`extract-tokens`) e o mapeamento valor antigo → token já existem — é o que a
  migração vai aplicar. Sem isso, falta o destino.
- Existe story/spec que pede a migração. Sem rastro, elicito o escopo — não invento fases.

## Passos

1. **Listo os clusters a migrar** a partir do shock report, com volume de ocorrências e impacto
   (quantas telas/áreas cada um toca).
2. **Priorizo por valor × risco.** Alto volume + baixo risco primeiro (vitória rápida, prova o
   modelo); alto risco/alta criticidade depois, com mais cuidado. Cada fase entrega valor sozinha.
3. **Defino as fases** — tipicamente:
   - **Fase 0 — fundação:** tokens cabeados, design system inicializado (já feito), sem trocar telas.
   - **Fase 1 — átomos de alto volume e baixo risco** (ex.: botão, input) com strangler: novo
     componente convive com o antigo até substituir.
   - **Fase N — moléculas/organismos e áreas críticas**, uma por vez, com validação.
4. **Para cada fase, especifico:** componentes alvo, mapeamento antigo → token/componente, critério
   de pronto, plano de rollback (como voltar se quebrar) e o gate de validação (@qa) e a11y.
5. **Marco os pontos de feedback.** Após cada fase, medir uso real e acessibilidade antes de seguir
   — a próxima fase só começa com a anterior validada.
6. **Defino fronteiras de autoridade no plano:** o que é design/construção do sistema (meu + build),
   o que é integração na app (@dev), validação (@qa), e que toda subida é do @devops.
7. **Escrevo** `docs/stories/{story}/migration-strategy.md`, rastreando cada fase à story/spec e ao
   cluster do shock report. Registro na File List.

## Critério de pronto (DoD)

- [ ] Clusters priorizados por valor × risco, com volume e impacto explícitos
- [ ] Fases definidas, cada uma entregando valor sozinha e com strangler onde aplicável
- [ ] Cada fase tem alvo, mapeamento antigo → token/componente, critério de pronto, rollback e gate
- [ ] Pontos de feedback/validação (uso + a11y) entre fases marcados
- [ ] Fronteiras de autoridade explícitas (dev integra, qa valida, devops sobe); rastro à story

## Falha / recuperação

- **Shock report ou tokens ausentes** → HALT; não planejo migração sem o caos medido e o destino.
- **Uma fase não tem rollback viável** → não a aprovo; quebro em passos menores até haver caminho de
  volta seguro.
- **Escopo cresce além da story** → paro e devolvo ao @sm/@po; não invento fases fora do rastro.