msd-core/docs/pt-BR/how-to/plan-a-phase.md

# Como planejar uma fase

**Objetivo:** Transformar decisões de fase e pesquisa em um plano de tarefas atômico e verificável, pronto para execução.

**Pré-requisitos:** `.planning/ROADMAP.md` deve existir. Um `{fase}-CONTEXT.md` gerado pelo `/msd-discuss-phase` é fortemente recomendado, mas não obrigatório.

---

## Execute o fluxo de planejamento padrão

```bash
/msd-plan-phase 2
```

Isso executa três estágios em sequência:

1. **Pesquisa** — Um subagente `msd-phase-researcher` investiga o domínio e escreve `{fase}-RESEARCH.md`.
2. **Planejamento** — Um subagente `msd-planner` lê o contexto, a pesquisa e os requisitos, e então escreve um ou mais arquivos `{fase}-{N}-PLAN.md`.
3. **Verificação** — Um subagente `msd-plan-checker` valida a qualidade do plano em oito dimensões e aciona um ciclo de revisão (até três iterações) até que os critérios de qualidade sejam aprovados.

Se nenhum número de fase for fornecido, o MSD Core seleciona a próxima fase não planejada do roadmap.

---

## Pular ou forçar a pesquisa

**Se o domínio for familiar e não houver necessidade de nova pesquisa:**

```bash
/msd-plan-phase 3 --skip-research
```

**Se o RESEARCH.md já existir, mas você quiser forçar uma atualização:**

```bash
/msd-plan-phase 3 --research
```

**Se você quiser executar apenas a pesquisa** — escrever o RESEARCH.md e encerrar antes do planejamento:

```bash
/msd-plan-phase --research-phase 4
```

Se o RESEARCH.md já existir, será solicitado que você atualize, visualize ou pule. Para forçar a atualização sem o prompt:

```bash
/msd-plan-phase --research-phase 4 --research
```

Para imprimir o RESEARCH.md existente no stdout sem acionar o pesquisador:

```bash
/msd-plan-phase --research-phase 4 --view
```

Nota: `--research-phase <N>` é uma flag do `/msd-plan-phase`. Não existe um comando standalone de fase de pesquisa — o comando standalone foi removido em favor desta flag.

---

## Planejar fatias verticais de funcionalidades em vez de camadas horizontais

**Se você quiser tarefas organizadas como fatias finas de ponta a ponta** (UI → API → BD por funcionalidade) em vez de por camada técnica:

```bash
/msd-plan-phase 1 --mvp
```

Na Fase 1 de um novo projeto sem resumos de fases anteriores, `--mvp` também produz `SKELETON.md` — um Walking Skeleton que cobre o scaffold do projeto, roteamento, uma leitura/escrita real no BD, uma interação real de UI e implantação de desenvolvimento.

É possível persistir o modo MVP para uma fase sem a flag, adicionando `**Mode:** mvp` à entrada daquela fase no ROADMAP.md.

---

## Exigir um teste falho por tarefa que adiciona comportamento

**Se você quiser a aplicação de TDD** — cada tarefa que adiciona comportamento começa com um teste falho antes da implementação:

```bash
/msd-plan-phase 1 --tdd
```

Combinável com `--mvp`:

```bash
/msd-plan-phase 1 --mvp --tdd
```

Isso produz fatias verticais onde cada tarefa que adiciona comportamento segue o ciclo RED → GREEN → REFACTOR. O planejador aplica `type: tdd` às tarefas elegíveis (lógica de negócio, endpoints de API, transformações de dados) e usa o `type: execute` padrão para UI, configuração e código de integração.

O modo TDD também pode ser persistido em config:

```bash
node msd-tools.cjs config-set workflow.tdd_mode true
```

---

## Replanejar usando feedback de revisão cruzada por IA

**Se você executou `/msd-review --phase N` e um `REVIEWS.md` existe:**

```bash
/msd-plan-phase 3 --reviews
```

O planejador lê o `REVIEWS.md` e revisa os planos para endereçar o feedback. Não pode ser combinado com `--gaps`.

**Se você quiser um ciclo automatizado** — replanejar e revisar até que não restem preocupações de nível HIGH:

```bash
/msd-plan-review-convergence 3
```

O ciclo de convergência executa ciclos de planejar → revisar → replanejar → revisar novamente (até três por padrão). Use `--max-cycles N` para substituir o limite máximo.

---

## Fechar lacunas após uma verificação falha

**Se o `VERIFICATION.md` existir com lacunas não resolvidas e você quiser replanejar apenas para essas lacunas:**

```bash
/msd-plan-phase 3 --gaps
```

A pesquisa é ignorada; o planejador lê as lacunas de verificação diretamente.

---

## Executar uma validação externa de bounce após o planejamento

**Se `workflow.plan_bounce_script` estiver configurado e você quiser validação externa do plano concluído:**

```bash
/msd-plan-phase 1 --bounce
```

Para pular o bounce mesmo que esteja habilitado em config:

```bash
/msd-plan-phase 1 --skip-bounce
```

---

## Suprimir confirmações interativas

```bash
/msd-plan-phase --auto
```

Ignora todos os prompts. Útil em pipelines automatizados. A pesquisa é ignorada se `research_enabled` for false em config.

---

## O que o plano produz

Uma execução bem-sucedida escreve:

| Arquivo | Finalidade |
|---|---|
| `{fase}-RESEARCH.md` | Pesquisa de domínio, auditoria de legitimidade de pacotes, arquitetura de validação |
| `{fase}-VALIDATION.md` | Mapeamento de testes Nyquist — os casos de teste que o plano deve satisfazer (Dimensão 8) |
| `{fase}-{N}-PLAN.md` | Plano de tarefas executável com frontmatter, atribuições de wave e critérios de aceitação |
| `{fase}/SKELETON.md` | Walking Skeleton (modo MVP, apenas Fase 1 de novo projeto) |

Cada PLAN.md contém tarefas com os campos obrigatórios `<read_first>` e `<acceptance_criteria>`. Cada entrada de `<acceptance_criteria>` é verificável como uma asserção de fonte, asserção de comportamento, comando de teste ou saída de CLI — nunca linguagem subjetiva.

Para a referência completa de campos, consulte o [schema do PLAN.md](../reference/plan-md.md).

### Dimensões de qualidade do plano

O `msd-plan-checker` valida os planos em oito dimensões antes de permitir a execução:

1. Atomicidade das tarefas — cada tarefa abrange uma única preocupação
2. Correção das dependências — a ordenação de waves é consistente
3. Verificabilidade dos critérios de aceitação — nenhum critério subjetivo
4. Completude do `<read_first>` — o arquivo sendo modificado está sempre listado
5. Valores concretos de `<action>` — sem instruções vagas como "alinhar com"
6. `must_haves` derivados do objetivo da fase
7. Cobertura de IDs de requisitos — cada ID de requisito da fase aparece em pelo menos um plano
8. Mapeamento de testes Nyquist — os planos abordam a estratégia de validação no VALIDATION.md

O ciclo de revisão executa até três vezes. Se os critérios de qualidade não forem aprovados após três iterações, o verificador apresenta os problemas remanescentes para revisão manual.

---

## Replanejamento de uma fase encerrada

Se uma fase possui `VERIFICATION.md` com `status: passed`, ela é considerada encerrada. Tentar replanejá-la resulta em erro. Se o encerramento foi incorreto, substitua com `--force`:

```bash
/msd-plan-phase 2 --force
```

Um aviso é emitido na transcrição e em quaisquer documentos de plano confirmados.

---

## Relacionados

- [Discutir uma fase](discuss-a-phase.md)
- [Executar uma fase](execute-a-phase.md)
- [Schema do PLAN.md](../reference/plan-md.md)
- [Comandos](../COMMANDS.md)