Mechanical rename produced by scripts/msd-rename.cjs: gsd/Gsd/GSD -> msd/Msd/MSD across contents and paths, upstream package/repo coordinates -> @golem15/msd-core and golem15com/msd-core. Deep links into upstream history, sibling upstream packages, the GSD-2 import feature, CHANGELOG.md and .changeset/ are kept as-is. Hand edits on top: MSD block-letter banner and logos, LICENSE copyright line, package/plugin identity, regenerated lockfile, install-tree fixtures, derived registries and benchmark baseline; migration checksum baseline re-locked (MSD keeps its own install state, so no install had applied the old sums); sort-order and regex-escaped expectations in tests adjusted.
177 lines
6.2 KiB
Markdown
177 lines
6.2 KiB
Markdown
# Como conduzir o MSD Core a partir de uma issue do rastreador
|
||
|
||
**Objetivo:** Levar uma única issue bem delimitada do GitHub, Linear ou Jira por todo o pipeline do MSD — desde o workspace isolado até o PR mesclado — usando apenas comandos já existentes no MSD Core, sem scripts customizados ou integrações com rastreadores.
|
||
|
||
**Pré-requisitos:** MSD Core está instalado. A issue tem escopo delimitado, critérios de aceitação observáveis e nenhum bloqueador upstream.
|
||
|
||
Para os conceitos e a justificativa de design por trás desse padrão, consulte [Orquestração orientada a issues explicada](../issue-driven-orchestration.md).
|
||
|
||
---
|
||
|
||
## Passo 1: Mapear a issue para uma fase
|
||
|
||
Abra sua issue no rastreador e decida como ela se encaixa no `ROADMAP.md`:
|
||
|
||
- **A issue corresponde a uma fase existente** → anote o número da fase e avance para o Passo 2.
|
||
- **A issue é um trabalho novo independente** → adicione uma fase:
|
||
|
||
```bash
|
||
/msd-phase "Descrição correspondente ao título da issue"
|
||
```
|
||
|
||
- **A issue é urgente e precisa ser inserida entre fases existentes** → insira uma fase decimal:
|
||
|
||
```bash
|
||
/msd-phase --insert 3 "Fix: descrição da issue"
|
||
```
|
||
|
||
Copie a URL da issue do rastreador. Você irá colá-la no `CONTEXT.md` no Passo 3 para que a rastreabilidade sobreviva à compactação de contexto.
|
||
|
||
---
|
||
|
||
## Passo 2: Criar um workspace isolado
|
||
|
||
Cada issue recebe seu próprio workspace — um git worktree com um diretório `.planning/` independente. Trabalhos parciais, planos abandonados e commits exploratórios ficam fora do `main`.
|
||
|
||
```bash
|
||
/msd-workspace --new --name my-issue-slug --repos . --strategy worktree
|
||
```
|
||
|
||
Entre no diretório do workspace antes de continuar:
|
||
|
||
```bash
|
||
cd ~/msd-workspaces/my-issue-slug
|
||
```
|
||
|
||
---
|
||
|
||
## Passo 3: Discutir a fase
|
||
|
||
Execute discuss-phase para definir as decisões de implementação antes que qualquer planejamento aconteça. Quando a sessão abrir, cole a URL da issue do rastreador na discussão para que ela seja capturada no `CONTEXT.md`.
|
||
|
||
```bash
|
||
/msd-discuss-phase N
|
||
```
|
||
|
||
O MSD pergunta sobre ambiguidades no escopo da issue — tratamento de erros, casos extremos, contratos de interface, escolhas tecnológicas. Suas respostas moldam o plano que se segue.
|
||
|
||
Se você já sabe todas as respostas e quer avançar rapidamente:
|
||
|
||
```bash
|
||
/msd-discuss-phase N --auto
|
||
```
|
||
|
||
---
|
||
|
||
## Passo 4: Planejar a fase
|
||
|
||
```bash
|
||
/msd-plan-phase N
|
||
```
|
||
|
||
O MSD cria agentes de pesquisa, lê suas decisões do `CONTEXT.md` (incluindo a URL da issue) e produz arquivos `PLAN.md` atômicos. Um verificador de planos valida cada plano antes de salvá-lo.
|
||
|
||
Se você quiser revisão por pares de CLIs externas de IA antes da execução (recomendado para mudanças significativas):
|
||
|
||
```bash
|
||
/msd-review --phase N
|
||
/msd-plan-phase N --reviews
|
||
```
|
||
|
||
Ou execute o loop completo de planejar–revisar–convergir até que não haja mais preocupações de nível HIGH:
|
||
|
||
```bash
|
||
/msd-plan-review-convergence N
|
||
```
|
||
|
||
---
|
||
|
||
## Passo 5: Executar a fase
|
||
|
||
Para execução interativa, fase por fase:
|
||
|
||
```bash
|
||
/msd-execute-phase N
|
||
```
|
||
|
||
Para uma execução sem supervisão por todas as fases restantes:
|
||
|
||
```bash
|
||
/msd-autonomous
|
||
```
|
||
|
||
Para um painel interativo onde você pode acompanhar o progresso e despachar trabalho entre fases:
|
||
|
||
```bash
|
||
/msd-manager
|
||
```
|
||
|
||
As três abordagens atualizam o `STATE.md`, fazem commit de cada tarefa atomicamente e executam o verificador pós-fase.
|
||
|
||
---
|
||
|
||
## Passo 6: Verificar o trabalho
|
||
|
||
```bash
|
||
/msd-verify-work N
|
||
```
|
||
|
||
O MSD percorre os critérios de aceitação do objetivo da fase (que reflete sua issue do rastreador) um de cada vez. Se algo falhar, o MSD diagnostica a causa raiz e cria um plano de correção. Execute novamente e re-verifique até que todas as verificações passem.
|
||
|
||
Trate `verification_failed` como um bloqueador mesmo quando o código parece correto — a falha geralmente revela um critério de aceitação não atendido da issue original.
|
||
|
||
---
|
||
|
||
## Passo 7: Revisar e publicar
|
||
|
||
Execute uma revisão de código antes de abrir o PR:
|
||
|
||
```bash
|
||
/msd-code-review N
|
||
/msd-code-review N --fix
|
||
```
|
||
|
||
Em seguida, crie o PR:
|
||
|
||
```bash
|
||
/msd-ship N
|
||
```
|
||
|
||
O MSD monta o corpo do PR a partir dos seus artefatos de planejamento: objetivo da fase, resumo das mudanças, requisitos atendidos, status de verificação e decisões-chave. Inclua `Closes #NNN` ou `Fixes #NNN` no corpo do PR (ou configure via `/msd-config`) para que a issue do rastreador seja fechada automaticamente quando o PR for mesclado.
|
||
|
||
---
|
||
|
||
## Passo 8: Registrar trabalho de acompanhamento
|
||
|
||
Ao trabalhar na issue, você frequentemente descobrirá trabalhos relacionados. Registre-os sem perder o contexto:
|
||
|
||
```bash
|
||
/msd-capture "Acompanhamento: descrição do trabalho descoberto" # Adicionar como tarefa
|
||
/msd-capture --seed "Ideia que vale uma fase futura" # Preservar para o próximo milestone
|
||
/msd-capture --backlog "Não urgente, mas vale registrar" # Arquivar no backlog
|
||
```
|
||
|
||
O MSD não publica no seu rastreador automaticamente. Criar uma issue no rastreador a partir dos acompanhamentos registrados é uma etapa manual separada — isso mantém a revisão humana no ciclo.
|
||
|
||
---
|
||
|
||
## Condicionais
|
||
|
||
| Situação | O que fazer |
|
||
|-----------|-----------|
|
||
| A issue é muito pequena (typo, mudança de config) | Pule workspace + discuss + plan; use `/msd-quick` em vez disso |
|
||
| A issue tem múltiplas subtarefas independentes | Use `/msd-manager` para paralelizar a execução entre planos |
|
||
| A issue está bloqueada em outra issue | Não inicie até que o bloqueador upstream seja resolvido; o MSD não possui poller automático de dependências |
|
||
| O escopo da issue se mostra maior do que o esperado durante a execução | Pare, execute `/msd-phase --insert N` para adicionar subfases, continue |
|
||
| Você quer pular a discussão interativa | Use a flag `--auto` com `/msd-discuss-phase`, ou defina `workflow.skip_discuss: true` para automação em todo o projeto |
|
||
| Múltiplas issues formam uma release coerente | Execute `/msd-new-milestone` para agrupá-las e `/msd-autonomous` para executar em sequência |
|
||
|
||
---
|
||
|
||
## Relacionados
|
||
|
||
- [Orquestração orientada a issues explicada](../issue-driven-orchestration.md)
|
||
- [Isolar trabalho com workspaces](isolate-work-with-workspaces.md)
|
||
- [Verificar e publicar](verify-and-ship.md)
|
||
- [índice de documentação](../README.md)
|