Files
msd-core/docs/pt-BR/how-to/drive-msd-from-a-tracker-issue.md
Jakub Zych a9a7a328e6 refactor: hard-fork GSD -> MSD (Make Software Done)
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.
2026-10-06 01:47:40 +02:00

177 lines
6.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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)