@spec-wave/cli 0.26.0 → 0.28.0

package/src/plugin/skills/preparar-feature/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: spec-wave-preparar-feature
+description: "Use para conduzir uma Feature do spec-wave pelo trecho que vai da spec pronta até ✅ Ready com as Stories e Tasks criadas no board: gera o plan.md, trata a crítica adversarial, valida, move a etapa, decompõe e confere o resultado. Gatilhos: 'gerar o plano', 'preparar a feature 12', 'deixar pronta para o dev', 'levar até ready', 'decompor a feature', 'roda o plan da #12'. Use mesmo quando o usuário nomear só um passo — os passos têm armadilhas encadeadas que só fazem sentido tratadas juntas. Para as specs de uma milestone inteira use preparar-specs; para um passo isolado e sem supervisão, as skills plan, ready ou decompose."
+allowed-tools:
+  - Bash(npx @spec-wave/cli@latest *)
+  - Bash(gh issue *)
+  - Bash(gh pr *)
+  - Bash(gh api *)
+  - Bash(git *)
+  - Read
+  - Edit
+  - Glob
+  - Grep
+---
+
+# Preparar Feature — de `spec.md` até ✅ Ready
+
+Conduz uma issue `[FEATURE]` pelo trecho do fluxo que vai da spec pronta até as Stories e Tasks criadas e visíveis no board.
+
+O valor desta skill não está em executar os passos — isso é fácil. Está em **saber o que verificar depois de cada um**. O fluxo tem pontos onde ele para em silêncio, e cada um já custou horas quando passou despercebido. Se você seguir só a sequência feliz, vai reportar sucesso sobre um estado quebrado.
+
+**Contexto:** leia `.spec-wave.json` (Read). Ausente → skill **setup**.
+
+## O ciclo, e por que ele não é uma sequência de comandos
+
+Cada passo publica o documento num **Pull Request próprio** (`spec-wave/<issue>-<doc>`), e o passo seguinte **lê da branch base**. O merge não é arrumação — é pré-requisito:
+
+```
+run --dry-run  →  run --yes  →  PR do documento  →  revisar  →  merge  →  git pull  →  próximo passo
+```
+
+Pular o merge não dá erro confuso: o `run` para e explica (`⛔ pr-pending`). Mas se você tentar contornar com `--step`, aí sim regenera por cima da revisão em curso e paga o modelo de novo.
+
+**Nada é gravado no seu checkout.** Não crie branch para "trabalhar nela", não commite documento à mão, não abra PR no fim — a CLI já faz tudo isso, uma vez por documento.
+
+## Modos de supervisão
+
+O padrão **para nos dois portões de julgamento** e pede aprovação: depois da crítica do plano, e antes do `decompose-apply`. Foi exatamente ali que a supervisão humana pegou defeitos reais — um plano que afirmava "esta feature não cria tabela" e trazia um `CREATE TABLE` logo abaixo, e uma task de E2E numa Story que não declarava depender do backend. A crítica automática passou pelos dois.
+
+Se o usuário pedir para você analisar e corrigir sozinho, siga — mas **leia cada artefato mesmo assim**. Não parar não é o mesmo que não olhar: corrija, siga, e registre no relatório final o que mudou e por quê.
+
+## Antes de começar
+
+Verifique tudo isto e **pare com um diagnóstico** se algo falhar:
+
+```bash
+npx @spec-wave/cli@latest --version                          # >= 0.27.0
+npx @spec-wave/cli@latest mode                               # actions ou local?
+gh issue view <n> --json labels,title -q '{t:.title,l:[.labels[].name]}'
+npx @spec-wave/cli@latest doctor
+```
+
+**O modo decide como você aciona cada passo**, e os dois são legítimos:
+
+| Modo | Aciona com | Observação |
+|---|---|---|
+| `actions` | a label (`spec-wave:plan`, `:ready`, `:decompose`…) | roda no CI |
+| `local` | `npx @spec-wave/cli@latest run <n>` | **não aplique label**: dispararia o Action e o passo rodaria duas vezes |
+
+Se o repositório está em `local`, aplicar uma label não gera nada — o job é pulado pelo `if: vars.SPEC_WAVE_EXECUTION != 'local'` e o run aparece verde e `skipped`, sem erro e sem documento. É o sintoma mais silencioso do fluxo. O caminho contrário também engana: em `actions`, o `run` não recusa, apenas avisa.
+
+Pare também se houver `spec-wave:critique-failed` ou `spec-wave:needs-human` — são portões humanos abertos de uma rodada anterior, e avançar por cima deles descarta a razão pela qual alguém parou.
+
+O slug vem do título da issue. Confirme olhando `docs/features/`, não deduza.
+
+### Onde começar depende do que já existe
+
+Não assuma que a Feature chega do zero — outra pessoa pode ter avançado antes de você. O `run --dry-run` responde isso sozinho, e é sempre o primeiro comando:
+
+```bash
+npx @spec-wave/cli@latest run <n> --dry-run
+```
+
+Ele diz o passo pendente e o motivo, olhando o disco, a branch base **e** as branches de artefato. **Se `plan.md` já existe, nunca force `--step plan`** — ele regera o documento do zero e descarta o que houver, inclusive revisão manual. Para corrigir um plano existente, `--step critique`.
+
+Leia também o último comentário 🔎 da issue; o marcador `<!-- spec-wave:critique kind=plan verdict=limpa -->` no topo diz o veredito sem você ter que interpretar o texto:
+
+```bash
+gh issue view <n> --comments --json comments -q '.comments[-1].body' | head -20
+```
+
+Um caso que o marcador revela: um `plan.md` gerado por um backend sem suporte a saída estruturada sai completo, mas a crítica aborta — e o comentário registra que o documento **não foi auditado**. Plano nunca auditado indo para `ready` é o sucesso aparente sobre estado não verificado que esta skill existe para evitar.
+
+### Os portões do `run`
+
+O `run` explica e para, saindo com código 2. Não force sem entender:
+
+| Portão | O que significa |
+|---|---|
+| `trigger-pending` | label de gatilho na issue. Em modo local ela é resíduo: **remova-a** em vez de usar `--force`, para a issue não mentir sobre o estado |
+| `pr-pending` | o documento está num PR aberto. Revise e mergeie — regerar descarta a revisão |
+| `branch-without-pr` | o commit passou e o PR não nasceu. Rode `doctor`: quase sempre é a opção de organização ou o `GH_PR_TOKEN` |
+| `stale-checkout` | o documento já está publicado na base e não no seu clone. `git pull` |
+| `needs-confirmation` | o passo cria issues. Revise o rascunho e confirme com `--apply` |
+| `inconsistent-state` | uma label afirma um documento que não existe — o título mudou depois de gerar? |
+
+### O modelo
+
+Para forçar um modelo num passo, aplique `spec-wave:model:<apelido>` — os apelidos válidos são os de `ai.modelAliases` no `.spec-wave.json`, e só esses. Um apelido que aponta para um modelo que o provider configurado não serve falha no passo, não na label.
+
+Confirme no log que o override pegou: `modelo: ... (origem: label)`.
+
+> **Uma lição que sobrevive à troca de provider:** quando um passo estoura o teto de turnos sem gerar nada, **troque o modelo antes de mexer no contexto**. Enxugar o `tech_context` em 14% não destravou nada, porque a entrada eram ~20k tokens; trocar o modelo entregou plano + crítica em minutos.
+
+---
+
+## 1 · Gerar o plano
+
+```bash
+npx @spec-wave/cli@latest run <n> --dry-run
+npx @spec-wave/cli@latest run <n> --yes
+```
+
+O `generate-plan` já critica o resultado ao final, no mesmo passo. O documento sai num PR.
+
+Antes deste passo, garanta que `.github/config/tech_context.yml` está **commitado e na base** — o passo lê o arquivo do repositório, não do seu disco.
+
+---
+
+## 2 · Tratar a crítica adversarial
+
+**Leia `reference/critica.md` antes de corrigir qualquer coisa.** Ele traz o que a crítica erra, como distinguir falso positivo de defeito real, e quando parar de iterar — é a parte desta skill que mais economiza tempo.
+
+O essencial:
+
+- **Confira o finding contra o arquivo antes de corrigir.** Cite o trecho que confirma ou refuta. É o que distingue "corrigi o que a IA mandou" de "verifiquei e o problema existe".
+- **Reaplique a crítica depois de editar**, mesmo com veredito `limpa` — ela é não-determinística, e a segunda passada costuma pegar a correção incompleta.
+- **Corrigir o documento à mão não é desvio** — é o que o fluxo pede quando a crítica reprova. Edite **no PR**, onde as edições são preservadas.
+
+Para recriticar sem regerar:
+
+```bash
+npx @spec-wave/cli@latest run <n> --yes --step critique
+```
+
+**`--step critique`, nunca `--step plan`.** O segundo regera o plano do zero e joga fora a correção — é o erro que faz o ciclo não convergir.
+
+Se aparecer `spec-wave:needs-human`, a crítica esgotou as tentativas. Pare e envolva o usuário — a label precisa sair à mão.
+
+**Mergeie o PR do plano antes de seguir.** O `validate` lê da base.
+
+---
+
+## 3 · Validar
+
+```bash
+npx @spec-wave/cli@latest run <n> --yes    # validate
+```
+
+Roda em segundos e **não usa IA**. Confere as seções obrigatórias de `spec.md` e `plan.md` e aplica `spec-wave:plan-approved`.
+
+### O validate NÃO move a etapa
+
+Primeiro ponto de parada silenciosa: a Feature passa na validação e **continua na etapa em que estava** — invisível na fila do TL, que lê `✅ Ready`. Nada no fluxo a move; o selo `plan-approved` é uma label, não uma coluna.
+
+```bash
+npx @spec-wave/cli@latest move <n> "ready"
+```
+
+Confirme depois lendo o board — a etapa nunca retrocede, então é melhor ver o estado do que supor.
+
+---
+
+## 4 · Decompor — o rascunho
+
+```bash
+npx @spec-wave/cli@latest run <n> --yes    # decompose
+```
+
+Gera `docs/features/<slug>/decomposition.md` e o critica. **Nenhuma issue é criada nesta etapa** — é de propósito, para haver um artefato revisável antes do irreversível.
+
+**Leia o rascunho e revise de verdade.** A crítica olha contradição com spec/plan; ela **não olha coerência do grafo de dependências**. O que vale conferir:
+
+- as linhas `**Depende de:**` refletem o que cada Story realmente precisa;
+- **nenhuma task de teste depende de coisa que a Story dela não declara** — já apareceu uma task pedindo E2E numa Story que declarava depender só da fundação; pelo grafo, ela rodaria antes de o backend existir e falharia;
+- identificadores com a grafia do domínio e sem acento, se essa for a convenção do repositório;
+- **nada contradiz as correções que você fez no `plan.md`** — isso precisa ser verificado, não presumido.
+
+Ao apresentar, mostre o grafo de dependências e a contagem de Stories/Tasks — é o que permite ao usuário julgar em segundos.
+
+Para corrigir, edite o `decomposition.md` **no PR** e reaplique `--step decompose`: o arquivo é criticado **como está**, não regerado. Recritique depois de editar mesmo que a passada anterior tenha vindo limpa.
+
+Se reprovar aqui, a superfície a corrigir é o **`decomposition.md`** — os achados citam `Story N` / `Task N.M`, que são títulos daquele arquivo. Confundir com o `plan.md` trava o ciclo.
+
+**Mas verifique se o defeito nasce no plano.** Já aconteceu de um achado apontar a `Task 4.1` com a causa no `plan.md`. Corrigir só o rascunho deixaria os dois divergentes, e a próxima geração traria o defeito de volta. Quando o achado descrever uma decisão técnica (e não um recorte de escopo), corrija nos dois.
+
+**Pare aqui e peça aprovação**, salvo instrução explícita em contrário. E mergeie o PR do rascunho: o apply lê da base.
+
+---
+
+## 5 · Aplicar
+
+```bash
+npx @spec-wave/cli@latest run <n> --yes --apply
+```
+
+**Isto é a aprovação humana** — não há nova crítica depois. É o passo mais caro de reverter: cria dezenas de issues, e desfazer exige fechar todas e remover `spec-wave:decomposed` à mão.
+
+### Sempre rode o detector depois
+
+```bash
+npx @spec-wave/cli@latest order <n>
+```
+
+Se aparecer **`Etapa: —`** nas Stories, o apply falhou no board **e saiu com sucesso** — o passo fica verde. As issues nascem sem etapa nenhuma, que é pior que Backlog: invisíveis em toda tela que filtra por etapa. A causa conhecida é o `GH_PROJECT_TOKEN` sem permissão de Projects na organização; o log mostra `Could not resolve to a node with the global id of 'PVT_...'`.
+
+O `order` só enxerga **Stories**. Confira as **Tasks por amostragem**, nas duas pontas da faixa de numeração criada.
+
+**Reparo**, uma issue por vez (cobre Etapa + Status, não o Work Item Type):
+
+```bash
+npx @spec-wave/cli@latest move <numero> "ready"
+```
+
+---
+
+## Relatório final
+
+Termine com o estado real, não com "concluído". O usuário precisa saber se pode mandar alguém pegar a Feature:
+
+```
+## <Feature> (#N) — <etapa atual>
+
+<grafo de dependências das Stories, com os números criados>
+
+| | |
+|---|---|
+| Documentos | spec.md · plan.md · decomposition.md |
+| Sub-issues | N Stories + M Tasks, todas em <etapa> |
+| PRs        | <os PRs de documento, e se foram mergeados> |
+
+### Correções aplicadas
+<o que você mudou no plan.md ou no decomposition.md, e por quê>
+
+### O que ainda bloqueia a implementação
+<ver abaixo>
+```
+
+### Verifique antes de dizer "pronta para o dev"
+
+Três coisas que o fluxo não checa e que já impediram a implementação de começar:
+
+1. **`specKit.command` configurado** no `.spec-wave.json` (ou a env `SPEC_WAVE_IMPLEMENT_CMD`). Sem isso o `implement` monta o contexto e para, sem acionar agente nenhum — o agente lê `.spec-wave/implement-<n>.md` e implementa direto. O `spec-wave dev-agent` **exige** essa configuração. O `doctor` reporta.
+2. **As dependências externas existem.** O `order` só enxerga as Stories filhas — ele não sabe que a spec declarou *outra Feature* como bloqueante. Leia a seção Dependências da `spec.md` e cheque se aquelas Features têm ao menos spec. Já aconteceu de duas bloqueantes não terem nem spec: as Stories de UI escreviam em arquivos de um wizard inexistente, enquanto as de backend podiam começar. Diga quais Stories dão para pegar hoje e quais não.
+3. **O `GH_PROJECT_TOKEN` funciona**, senão `code-review.yml` e `qa.yml` também vão falhar em mover cards durante a implementação, provavelmente em silêncio. O `doctor` verifica a **presença** do secret, nunca a validade — um token presente e sem permissão passa despercebido.

package/src/plugin/skills/preparar-feature/reference/critica.md

@@ -0,0 +1,88 @@
+# A crítica adversarial na prática
+
+O que este arquivo acrescenta ao fluxo: a crítica **não é um veredito**, é uma amostra. Tratá-la
+como veredito produz os dois erros caros — aceitar um documento defeituoso porque a passada veio
+limpa, e reescrever lógica correta porque um finding disse para reescrever.
+
+## A crítica é não-determinística
+
+Passadas sucessivas sobre o **mesmo arquivo** dão vereditos diferentes. Três passadas medidas sobre
+o mesmo `plan.md`, sem editar nada entre a primeira e a segunda além da correção que a primeira
+pediu:
+
+| Passada | Achados |
+|---|---|
+| 1 | 1 menor — um refetch disparado por posição quando o item já vinha no payload |
+| 2 | 2 menores — a correção da passada 1 tinha ficado **pela metade** (uma seção corrigida, outra não, o plano contradizendo a si mesmo) + uma regra descrita de duas formas |
+| 3 | 2 menores, ambos novos — do tipo "o plano não explica X", não mais contradição |
+
+Em outra Feature, duas passadas sobre o mesmo arquivo e o mesmo modelo deram
+`✅ Nenhuma contradição encontrada` e depois `1 GRAVE` — e o defeito já estava lá na primeira.
+
+**Leia "nenhuma contradição encontrada" como *um revisor não achou nada nesta passada*.**
+
+### Três consequências práticas
+
+1. **Reaplique a crítica depois de editar**, mesmo com veredito `limpa`. Foi a segunda passada que
+   pegou a correção incompleta, e custa um minuto.
+2. **Findings "menores" podem ser substantivos.** O primeiro do exemplo era um round-trip
+   desperdiçado no caso mais comum — não bloqueava o `ready`, mas era defeito real.
+3. **Saiba parar.** Quando os achados viram "o plano não explica X" em vez de "o plano se
+   contradiz", o retorno virou marginal. Corrija o que você mesmo introduziu e siga.
+
+## Antes de corrigir, confira o finding contra o arquivo
+
+A crítica produz os dois tipos de erro, e eles pedem respostas opostas.
+
+**Falso positivo.** O padrão já observado: o texto do finding termina em "não é contradição real" e
+a severidade sai `grave` mesmo assim. Aí o ajuste é tornar o documento **mais explícito no ponto
+citado**, não reescrever a lógica. Reescrever a lógica de um plano correto por causa de um finding
+mal calibrado é o pior desfecho disponível: custa a revisão e introduz o defeito que não existia.
+
+**Defeito real.** Também já observado: o plano dizia duas vezes "esta feature não cria tabela nem
+coluna (RN15)" e trazia um `CREATE TABLE` com uma coluna de texto livre, violando de quebra uma
+decisão registrada no `tech_context`. Nenhuma leitura superficial pegaria — as duas afirmações
+estavam a páginas de distância.
+
+**Cite o trecho do arquivo que confirma ou refuta o finding.** É o que distingue "corrigi o que a
+IA mandou" de "verifiquei e o problema existe", e é o que o usuário precisa para julgar a sua
+correção sem reler o documento inteiro.
+
+## Qual superfície corrigir
+
+O achado cita âncoras, e a âncora diz onde corrigir:
+
+| O achado cita | Corrija |
+|---|---|
+| seções do plano técnico | `plan.md` |
+| `Story N` / `Task N.M` | `decomposition.md` — são títulos daquele arquivo |
+
+Confundir as duas trava o ciclo: você corrige o documento errado, recritica, e o mesmo achado volta.
+
+**Mas verifique se o defeito nasce acima.** Um achado que aponta uma `Task` pode ter a causa no
+`plan.md`. Corrigir só o rascunho deixa os dois divergentes, e a próxima geração traz o defeito de
+volta. A regra: se o achado descreve uma **decisão técnica**, corrija nos dois; se descreve um
+**recorte de escopo**, o rascunho basta.
+
+## Recriticar sem regerar
+
+```bash
+npx @spec-wave/cli@latest run <n> --yes --step critique
+```
+
+**Nunca `--step plan` para isso.** Ele regera o documento do zero e descarta a correção — é o erro
+que faz o ciclo não convergir, porque cada rodada recomeça do mesmo lugar.
+
+Existe também `critique --file <caminho>`, que é **consulta**: não comenta na issue, não aplica
+label e não consome tentativa. Útil para conferir uma correção antes de gastar o portão.
+
+## Quando a crítica esgota
+
+Depois de N reprovas seguidas (3, por padrão) o fluxo aplica `spec-wave:needs-human` e para.
+
+Isso não é um erro a contornar — é o fluxo dizendo que a correção automática não está convergindo.
+Pare e envolva o usuário. A label sai à mão, e sair dela sem resolver a causa só adia o mesmo
+impasse para a próxima passada.
+
+O mesmo vale para `spec-wave:critique-failed`: o caminho de retomada é **corrigir o documento e
+recriticar**, nunca regerar.

package/src/plugin/skills/preparar-specs/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: spec-wave-preparar-specs
+description: "Use para gerar o spec.md de TODAS as Features de uma milestone de uma vez: confere o ambiente antes de gastar modelo, gera, valida a estrutura, revisa o conjunto procurando contradições ENTRE as specs, mergeia os PRs e move as issues para 📋 Spec. Gatilhos: 'gera as specs da v06', 'roda os specs da milestone X', 'quero todas as features da v05.2 especificadas', 'gera as specs que faltam', 'quais features estão sem spec?', 'preciso das specs prontas antes de gerar os planos'. NÃO use para uma Feature isolada — aí é a skill spec (um passo) ou preparar-feature (a Feature inteira, até Ready)."
+allowed-tools:
+  - Bash(npx @spec-wave/cli@latest *)
+  - Bash(gh issue *)
+  - Bash(gh pr *)
+  - Bash(gh run *)
+  - Bash(gh api *)
+  - Bash(git *)
+  - Read
+  - Glob
+  - Grep
+---
+
+# Specs de uma milestone inteira
+
+Levar todas as Features de uma milestone de "sem spec" até "spec revisada e mergeada na base, issue em 📋 Spec". São seis fases e a ordem importa: cada uma existe para que a seguinte não desperdice trabalho caro.
+
+O custo real aqui não é tempo — é que **cada geração paga um modelo**. Um erro de configuração descoberto na sétima Feature custa sete gerações. Por isso a Fase 0 existe, e por isso a Fase 1 para na primeira falha em vez de seguir em frente.
+
+**Contexto:** leia `.spec-wave.json` (Read). Ausente → skill **setup**.
+
+## Fase 0 — Preflight (nunca pule)
+
+```bash
+npx @spec-wave/cli@latest preflight --milestone <nome>
+```
+
+Um comando reporta: token utilizável, modo de execução (config × variável do repositório), se a publicação por Pull Request funciona, as Features da milestone com o estado do `spec.md` de cada uma, e labels de gatilho grudadas. Sai com código 1 se houver bloqueio. `--json` devolve o mesmo relatório para você ramificar.
+
+**Leia a coluna de estado de cada Feature antes de agir** — ela não é `existe`/`não existe`:
+
+| Estado | O que significa | O que fazer |
+|---|---|---|
+| `· gerar` | não existe em lugar nenhum | entra na rodada |
+| `✓ na base` / `✓ no disco` | já mergeada | não gerar |
+| `⏳ em PR aberto` | gerada, aguardando revisão/merge | **não gerar** — regerar descarta a revisão e paga o modelo de novo |
+| `⚠ em branch sem PR` | commit passou, PR não nasceu | abrir o PR; ver `reference/armadilhas.md` |
+| `? indeterminado` | a consulta falhou | confirmar antes, para não pagar duas vezes |
+
+Se qualquer bloqueio aparecer, **resolva antes de gerar**. As causas estão em `reference/armadilhas.md`; leia esse arquivo agora se for a primeira vez que você roda esta skill neste repositório.
+
+Confirme **duas** coisas com o usuário antes de começar — é a última chance barata de descobrir que a milestone errada foi escolhida, e a única de decidir onde a rodada roda:
+
+1. **a lista de Features** que serão geradas;
+2. **o modo de execução** — `actions` ou `local`. O preflight diz qual está configurado hoje; isso é o *default* da pergunta, não a resposta. Os custos dos dois são diferentes o bastante (Fase 1) para a escolha ser dele, não sua.
+
+## Fase 1 — Gerar
+
+**O modo de execução decide como acionar** — e ele é o que o usuário respondeu na Fase 0, não o que o preflight encontrou configurado:
+
+| Modo | Como acionar | O que custa |
+|---|---|---|
+| `actions` | aplicar a label `spec-wave:spec` | minutos de GitHub Actions; roda em paralelo e não prende a máquina |
+| `local` | `npx @spec-wave/cli@latest run <issue>`, com `--dry-run` antes | nenhum minuto de CI; alguns minutos por Feature, mas a máquina fica ocupada |
+
+**Se a resposta diferir do que está configurado, troque o modo antes de gerar** — não tente acionar "do outro jeito" por cima da configuração atual:
+
+```bash
+npx @spec-wave/cli@latest mode <actions|local>
+```
+
+Três consequências que impedem essa troca de ser um detalhe desta rodada — diga-as ao usuário **antes** de executar, porque duas delas sobrevivem à rodada:
+
+- **a escolha vale para todo mundo.** O `mode` escreve os dois lados do interruptor: o `.spec-wave.json` e a variável de repositório `SPEC_WAVE_EXECUTION`, que o `if:` de cada job avalia. Quem rodar o fluxo depois de você herda o modo que você deixou.
+- **a variável exige permissão de administração.** Sem ela o comando grava só o config e diz o que faltou — e os dois lados passam a divergir: você acha que desarmou os workflows, e eles continuam disparando.
+- **o `.spec-wave.json` fica modificado localmente.** Commite, senão quem clona o repositório (dev-agent, Actions) continua lendo o modo antigo.
+
+**No modo `local`, NÃO aplique label de gatilho.** O `run` não aplica nenhuma, e aplicá-la à mão põe a label e o `run` no mesmo passo da mesma Feature — o modelo é pago duas vezes.
+
+**Os dois modos fazem a mesma coisa:** geram o documento e o publicam **via API, em branch própria por Feature (`spec-wave/<issue>-spec`), abrindo um PR**. Nada é escrito no seu checkout — confirme com `git status` na primeira geração.
+
+Cada `run` termina dizendo em qual PR o documento saiu, e avisando que *o próximo passo do fluxo lê o documento da branch base* — ou seja, o merge é pré-requisito do `plan`, não um detalhe de arrumação.
+
+### Uma canária, depois em paralelo
+
+Nem tudo de uma vez, nem tudo em série:
+
+1. **Gere UMA sozinha e espere.** Ela custa uma geração e responde tudo que é sistêmico: credencial válida, permissão de publicar, modo correto, PR abrindo de fato. Um erro descoberto aqui custa 1 geração; descoberto na sétima, custa 7. **Se a canária falhar, não dispare mais nada.**
+2. **Passando a canária, o resto sai em até 4 trilhas simultâneas.**
+
+Paralelizar é seguro porque o lock da CLI é **por issue** (`.git/spec-wave/run-<n>.lock`) e a publicação é por API, em branch própria — issues diferentes nunca disputam nada.
+
+O teto de 4 não vem da CLI, vem do backend: no modo `local` quem gera é o agente desta máquina, e outras sessões podem estar usando o mesmo. Vale conferir com `pgrep -af "spec-wave run"` antes. Em `actions` nada disso se aplica: o paralelismo é do próprio GitHub.
+
+**Rode em background, nunca em primeiro plano.** Uma spec leva minutos; uma ferramenta com timeout curto mata o comando no meio — e o custo já foi pago.
+
+**Ao falhar, a pergunta é sempre a mesma:** *isto é específico desta Feature, ou vai acontecer com todas?* Leia o log (`gh run view <id> --log-failed | tail -40`) ou o erro da CLI antes de qualquer outra coisa. Onde a falha aconteceu já indica a resposta:
+
+- **Na canária** — trate como sistêmico até prova em contrário e **não dispare as trilhas**. Credencial, permissão, publicação e configuração falham assim.
+- **Numa trilha, com a canária tendo passado** — quase sempre pontual. As outras trilhas seguem; não as interrompa para investigar uma.
+
+**`error_max_turns` é o caso pontual mais comum** — o modelo gasta o teto de turnos explorando o repositório e não chega a escrever. A própria CLI classifica: se as chamadas de ferramenta são **distintas**, foi exploração (varia entre execuções) e **repetir no mesmo modelo costuma bastar**; se elas **se repetem**, é loop degenerado e repetir só paga a mesma perambulação de novo. Só nesse segundo caso entram trocar de modelo ou subir `maxTurns` — e essas são decisões do usuário, porque custam mais caro. O teto vive no frontmatter do prompt da CLI, não no `.spec-wave.json`.
+
+Diga ao usuário o que encontrou e o que recomenda, em vez de tentar contornar sozinho: várias saídas possíveis (mudar o modo, mexer em proteção de branch, trocar credencial) são decisões dele.
+
+## Fase 2 — Validar estrutura
+
+Barato e determinístico, então roda em todas antes da revisão cara.
+
+**Não use `spec-wave validate` aqui:** ele valida spec **e** plan juntos, e nesta altura o `plan.md` não existe — reprovaria toda Feature da milestone e ainda consumiria a label `spec-wave:ready`. A conferência desta fase é de leitura.
+
+O que olhar em cada spec:
+
+- as seções obrigatórias estão presentes e com o nome exato. O gerador escreve seis (`Visão Geral`, `Regras de Negócio`, `Fluxos`, `Critérios de Aceite`, `Dependências`, `Requisitos Não-Funcionais`) e o `validate` mais tarde vai exigir três delas **byte a byte** — `Visão Geral`, `Critérios de Aceite` e `Requisitos Não-Funcionais`. Título divergente ("encontrei X, esperava Y") se resolve renomeando, não regerando;
+- nenhum sinal de corte: bloco de código não fechado, parêntese aberto na última linha. Um documento truncado passa na conferência de seções e vale menos que documento nenhum;
+- conte os `[TODO: requer esclarecimento` de cada spec. O número não é defeito — é o mapa do que ficou em aberto, e vai para o relatório final.
+
+Se uma spec estiver estruturalmente quebrada, **não reaplique `spec-wave:spec` por reflexo**: essa label **sobrescreve** o arquivo. Se o documento já foi revisado ou editado, regenerar joga fora a revisão.
+
+## Fase 3 — Revisar conteúdo
+
+Aqui está a maior parte do valor, e é o que distingue esta skill de rodar sete comandos em sequência. Leia `reference/revisao.md` — ele traz o método e as classes de problema que aparecem de verdade, com exemplos reais.
+
+As specs ainda não estão na base neste ponto — cada uma vive na branch do seu PR. Leia direto de lá, sem checkout:
+
+```bash
+git fetch origin
+git show origin/spec-wave/<issue>-spec:docs/features/<slug>/spec.md
+```
+
+Em resumo: leia as specs **como conjunto**, não uma a uma. Problemas de spec isolada o gerador já evita bem; o que ele não consegue ver é a relação entre documentos — regra que duas features contam de formas diferentes, dependência circular, feature que aponta para um lugar que não existe, e afirmações que a própria rodada tornou falsas.
+
+Separe o que encontrar em duas classes, porque elas têm destinos diferentes:
+
+- **Achado material** — muda o desenho de alguma feature, ou tem risco em produção. Vai como comentário na issue, com a regra que o originou e a decisão necessária.
+- **Lacuna paramétrica** — falta um número, um prazo, um limiar. Não bloqueia; agrupe por tema no relatório final, porque doze delas costumam ser uma decisão só.
+
+## Fase 4 — Mergear os PRs
+
+A Fase 1 já abriu um PR por Feature; **não há nada a publicar**. O trabalho aqui é mergear os que a revisão aprovou.
+
+Isso reordena as fases de propósito: a revisão da Fase 3 acontece **antes** do merge, lendo o conteúdo direto das branches, e o merge passa a ser o registro de que a revisão terminou.
+
+Para cada PR: confira que o check obrigatório passou e mergeie. Um PR por Feature é bom para o histórico (cada spec rastreável à sua issue), então não tente consolidar num PR único — consolidar exigiria desfazer o que a ferramenta fez sozinha, sem ganho real.
+
+Achado material **não** bloqueia o merge. A spec registra o que foi gerado a partir da fonte normativa; o achado é decisão do PO e vive na issue. Segurar o merge só deixa a spec invisível para quem precisa dela — inclusive para o `plan`, que lê da branch base.
+
+Ao final, reconcilie o checkout com `git pull --rebase`.
+
+## Fase 5 — Mover o board
+
+Depois do merge, para cada Feature:
+
+```bash
+npx @spec-wave/cli@latest move <n> "📋 Spec"
+```
+
+Use o comando, não mutação manual no board — ele embute as regras do fluxo. E note que **a Etapa nunca retrocede**: uma vez movida, não volta por comando. Por isso este passo vem *depois* do merge, quando as specs de fato existem na base, e não antes.
+
+Confirme lendo o board de volta, não pela saída do comando.
+
+## Fase 6 — Relatório
+
+Entregue ao usuário, nesta ordem — do que exige decisão para o que é registro:
+
+1. **Achados materiais**, se houver, com link do comentário em cada issue. É o que ele precisa decidir antes de gerar planos.
+2. **Placar**: N/N specs na base, PRs mergeados, issues em 📋 Spec.
+3. **Tabela** por Feature: issue, nome, linhas, TODOs.
+4. **Lacunas paramétricas agrupadas por tema**, com a contagem.
+5. **O que ficou aberto** — dependências de features sem spec, inversões de sequenciamento entre milestones, dívida operacional.
+
+Um plano gerado sobre uma spec cuja regra vai mudar é retrabalho garantido. Se a Fase 3 produziu achados materiais, diga isso explicitamente ao recomendar o próximo passo.
+
+## Referências
+
+- `reference/armadilhas.md` — as armadilhas operacionais deste fluxo, cada uma com a causa e o sintoma. Leia antes da Fase 1 na primeira vez, e sempre que algo falhar de um jeito que não faz sentido.
+- `reference/revisao.md` — o método da Fase 3 e as classes de problema que aparecem de verdade, com exemplos reais.
+
+Depois desta skill, o passo natural de cada Feature é o plano técnico: skill **preparar-feature** (leva uma Feature de spec até ✅ Ready com Stories e Tasks) ou skill **plan** (só o `plan.md`).