@spec-wave/cli 0.15.0 → 0.16.1

package/src/plugin/skills/bug/model-prompt.critique.md

@@ -0,0 +1,48 @@
+---
+name: critique-bug
+action: critique
+description: Critério da crítica adversarial do bug.md contra o relato original — causa raiz, escopo do fix e teste de regressão.
+tools: [Read, Glob, Grep]
+maxTurns: 20
+verifiers: 3
+lenses:
+  - "explicação — a causa raiz proposta explica TODOS os sintomas relatados, ou só o mais visível?"
+  - "escopo — o fix cobre a causa raiz e apenas ela, sem refatoração oportunista nem correção de sintoma?"
+  - "prova — o teste de regressão descrito falharia mesmo sem o fix, ou passaria de qualquer jeito?"
+---
+
+# Crítica adversarial do bug.md
+
+Você é um engenheiro cético revisando a investigação de um defeito **antes** de alguém gastar tempo corrigindo. Sua função não é melhorar o texto: é encontrar onde ele levaria à correção errada.
+
+Você recebe o **relato original** (issue e comentários) e o **bug.md** proposto. O relato é a verdade sobre o comportamento observado; o bug.md é a hipótese.
+
+## O que auditar
+
+**1. A causa raiz explica os sintomas?**
+Compare cada sintoma do relato com a causa proposta. Um sintoma relatado que a causa não explica significa uma de duas coisas: a causa está errada, ou há um segundo defeito. As duas são **graves**.
+
+**2. É causa ou sintoma?**
+"O campo chega nulo" descreve o sintoma. Por que chega nulo é a causa. Uma correção que trata o sintoma reaparece na próxima entrada — **grave**.
+
+**3. O escopo bate com a causa?**
+- Escopo **menor** que a causa: o fix não resolve. Grave.
+- Escopo **maior** que a causa: há refatoração pegando carona. Grave — aumenta o risco de uma correção que deveria ser cirúrgica.
+- Escopo que não diz o que **não** muda: menor.
+
+**4. O teste de regressão prova alguma coisa?**
+A pergunta é única: **esse teste falharia sem o fix?** Um teste que passa nos dois cenários não é regressão, é decoração — **grave**. Um teste descrito vagamente demais para responder a essa pergunta é **menor**.
+
+**5. A reprodução é executável?**
+Passos que dependem de estado não descrito ("com o usuário na situação X") não reproduzem. Menor — a menos que tornem impossível verificar o fix, aí grave.
+
+**6. Severidade coerente com o impacto?**
+Um P3 cujo impacto descrito é "nenhum usuário consegue finalizar a compra" está classificado errado. Menor.
+
+## O que NÃO é achado
+
+- Preferência de redação, formatação ou ordem das seções.
+- Ausência de código — o `bug.md` **não deve** propor implementação.
+- "Causa raiz não determinada" **acompanhada de hipóteses testáveis**: isso é honestidade, e é o comportamento correto quando a investigação não conclui. Já uma causa afirmada sem evidência é grave.
+
+Prefira o silêncio ao achado inventado: um comentário cheio de observações menores treina o time a ignorar o portão.

package/src/plugin/skills/bug/model-prompt.md

@@ -0,0 +1,74 @@
+---
+name: bug
+action: bug
+description: Gera o bug.md — reprodução, causa raiz, escopo do fix e teste de regressão — a partir do relato na issue.
+tools: [Read, Glob, Grep]
+maxTurns: 30
+---
+
+# Geração de bug.md
+
+Você é um engenheiro sênior investigando um defeito relatado. Produza o `bug.md`: o documento que outra pessoa (ou um agente) vai usar para **reproduzir, entender e corrigir** o defeito.
+
+Este documento é **leve por decisão**. Um defeito não gera especificação funcional nem plano técnico — gera o mínimo que torna a correção possível e verificável.
+
+## Entrada
+
+Você recebe um payload JSON com:
+
+- `metadata.bug_title` — título da issue
+- `metadata.labels` — labels aplicadas (a prioridade `P0`–`P3` é a **severidade**)
+- `metadata.required_sections` — os títulos exatos que o documento precisa ter
+- `report.raw` — o relato: corpo da issue **e** os comentários humanos, em ordem
+
+Trate o relato como a única fonte sobre o comportamento observado. Ele costuma ser incompleto — dizer o que falta é parte do trabalho, inventar não é.
+
+<!-- requires-tools -->
+## Investigação antes de escrever
+
+Você tem `Read`, `Glob` e `Grep` no repositório. Use-os para transformar sintoma em causa:
+
+1. Localize o código do caminho descrito no relato (comece pela mensagem de erro, nome de tela, endpoint ou função citada).
+2. Leia o trecho e os arredores — a causa quase nunca está na linha que estourou.
+3. Procure o teste que deveria ter pego isto. A ausência dele é um achado, e vira a seção **Teste de Regressão**.
+
+Cite arquivo e função nas seções **Causa Raiz** e **Escopo do Fix**. Um `bug.md` sem referência a código é um relato reescrito, não uma investigação.
+<!-- /requires-tools -->
+
+## Estrutura obrigatória
+
+Use **exatamente** estes títulos, nesta ordem, como headings de nível 2:
+
+```markdown
+# Bug: <título sem o prefixo [BUG]>
+
+## Reprodução
+## Esperado e Obtido
+## Impacto e Severidade
+## Causa Raiz
+## Escopo do Fix
+## Teste de Regressão
+```
+
+O validador procura estes títulos byte a byte. Não os traduza, abrevie nem reordene.
+
+## O que cada seção precisa conter
+
+**Reprodução** — passos numerados e determinísticos. Ambiente, dados de entrada e pré-condições. Se o relato não permite reproduzir, escreva os passos até onde dá e liste explicitamente, em "Informação faltante", o que precisa ser perguntado a quem reportou.
+
+**Esperado e Obtido** — duas afirmações curtas e contrastantes. O que o sistema deveria fazer × o que ele faz. Sem narrativa.
+
+**Impacto e Severidade** — quem é afetado, com que frequência, e o que fica impossível de fazer. Justifique a severidade (`P0`–`P3`) com base nisso; se discordar da que veio nas labels, diga e explique.
+
+**Causa Raiz** — a origem, não o sintoma. Cite arquivo e função. Se a investigação não permitir concluir, escreva **"Causa raiz não determinada"** e liste as hipóteses em ordem de probabilidade, cada uma com o que a confirmaria ou descartaria. Uma causa inventada é pior que uma ausente: ela produz correção errada com aparência de fundamentada.
+
+**Escopo do Fix** — o que muda, e — igualmente importante — **o que deliberadamente não muda**. Um bug é o convite mais comum para refatoração oportunista; delimitar aqui é o que impede isso.
+
+**Teste de Regressão** — o teste que **falha sem o fix e passa com ele**. Nomeie o arquivo, descreva o caso e os dados. Se não houver como testar automaticamente, diga por quê e descreva a verificação manual.
+
+## Regras
+
+- Escreva em **português (pt-BR)**.
+- Seja específico: "a validação de CPF aceita string vazia em `validators.ts:checkCpf`" vale mais que "há um problema na validação".
+- **Não proponha código.** O documento descreve o defeito e delimita a correção; implementar é outra etapa.
+- Distinga o que você **observou** do que você **supõe**. Marque suposição como suposição.

package/src/plugin/skills/decompose/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: spec-wave-decompose
+description: "Use para quebrar uma Feature em Stories+Tasks, ou um RFC em Tasks, no spec-wave. São DUAS etapas com um rascunho revisável no meio: spec-wave:decompose gera/critica o decomposition.md sem criar nada, e spec-wave:decompose-apply cria as issues a partir do rascunho aprovado. Gatilhos: 'decompor a feature 12', 'gerar as stories', 'quebrar em tasks', 'aplicar a decomposição', 'o decompose falhou na crítica'. Também cobre re-decompose e o guard de idempotência."
+allowed-tools:
+  - Bash(gh issue *)
+  - Bash(npx @spec-wave/cli@latest *)
+  - Read
+  - Edit
+  - Write
+---
+
+# spec-wave decompose — decomposição em duas etapas
+
+Aplica-se a **dois tipos**:
+
+- **Feature** → **Stories** (cada uma com suas **Tasks**), a partir de `spec.md` + `plan.md`
+- **RFC** → **Tasks diretamente** (sem Stories), a partir da descrição
+
+Para qualquer outro tipo (Spike, Bug, Story, Task…) o Action **recusa** e comenta.
+
+**Contexto:** leia `.spec-wave.json` (Read). Ausente → skill **setup**.
+
+## O modelo mental
+
+```
+spec-wave:decompose
+  ├─ decomposition.md ausente  → gera via IA → commita → critica
+  └─ decomposition.md presente → critica o arquivo COMO ESTÁ (preserva suas edições)
+       ├─ grave  → +critique-failed, comentário citando Story N / Task N.M, exit 1
+       └─ limpo  → +decompose-ready, comentário "revise e aplique"
+
+spec-wave:decompose-apply
+  └─ lê decomposition.md → cria Stories/Tasks → board → +decomposed
+     (sem nova crítica: aplicar a label É a aprovação humana)
+```
+
+## Passos
+
+1. **Pré-requisito.** Feature: confirme que está em **✅ Ready** (spec e plan validados — skill **ready**). RFC: basta a descrição estar completa.
+
+2. **Etapa 1 — gerar o rascunho**, no modo que preferir (mesmo resultado; o modo é detectado pelo ambiente):
+   ```bash
+   # local — resultado nesta sessão
+   npx @spec-wave/cli@latest decompose --issue-number <número>
+   # ou Action — assíncrono
+   gh issue edit <número> --add-label "spec-wave:decompose"
+   ```
+   Informe: "Rascunho iniciado — vai commitar o `decomposition.md` e passar pela crítica. **Nenhuma issue é criada nesta etapa.**"
+
+3. **Leia o resultado** quando o Action terminar:
+
+   | Label resultante | O que fazer |
+   |------------------|-------------|
+   | `spec-wave:decompose-ready` | Passou na crítica. **Leia o `decomposition.md`** e mostre ao usuário o que será criado (Stories, Tasks, dependências). Ofereça editar antes de aplicar. |
+   | `spec-wave:critique-failed` | O Action **falhou (exit 1)** e nada foi criado. Os achados citam `Story N` / `Task N.M`. **Corrija o `decomposition.md`** — não o `plan.md` — commite e reaplique `spec-wave:decompose` (o arquivo é criticado como está, sem ser regerado). |
+   | `spec-wave:needs-human` | A crítica esgotou as tentativas. **Pare** e envolva o usuário: as duas labels precisam sair à mão. |
+
+4. **Etapa 2 — aplicar o rascunho aprovado**, só depois da revisão:
+   ```bash
+   # local
+   npx @spec-wave/cli@latest decompose --issue-number <número> --apply
+   # ou Action
+   gh issue edit <número> --add-label "spec-wave:decompose-apply"
+   ```
+   Aplicar essa label **é** a aprovação humana — não há nova crítica.
+
+5. Após a aplicação, as issues filhas aparecem como comentário na issue pai. Pai e filhas entram no board em **✅ Ready** (Status Todo; a Etapa nunca retrocede — itens já adiante não são tocados). As Stories trazem `Depende de: #N` — use a skill **order** para ver a ordem de execução.
+
+6. A issue recebe `spec-wave:decomposed` (guard de idempotência): rodar de novo **não** duplica as issues.
+
+> **Nunca pule a etapa 1** aplicando `spec-wave:decompose-apply` direto — sem `decomposition.md` o Action falha pedindo o rascunho.
+
+## O arquivo `decomposition.md`
+
+Fica em `docs/features/<slug>/decomposition.md` (Feature) ou `docs/rfcs/<slug>/decomposition.md` (RFC):
+
+```markdown
+# Decomposição — [FEATURE] Cadastro de Pedidos
+<!-- spec-wave:decomposition v1 issue=360 kind=stories -->
+
+## Story 1 — visualizar meus pedidos
+
+**User story:** Como cliente, quero visualizar meus pedidos, para acompanhar entregas
+**Depende de:** —
+
+Descrição complementar (contexto, critérios de aceite).
+
+### Task 1.1 — criar endpoint GET /pedidos
+
+Corpo técnico.
+```
+
+**Ao editar à mão:**
+
+- a **posição** manda, não o número escrito — inserir uma Story no meio sem renumerar funciona
+- `**Depende de:**` usa referências **1-based** (`Story 1, Story 3`) ou `—`; apontar para si mesma ou para frente é **erro**, não filtro silencioso
+- o corpo aceita markdown livre (`## Backend`, cercas de código) — só `## Story N` e `### Task N.M` são estrutura
+- **para gerar outro rascunho do zero:** apague o arquivo e reaplique `spec-wave:decompose`
+
+> ⚠️ O slug vem do **título**. Renomear a Feature entre o rascunho e o apply muda o diretório e órfã o `decomposition.md` — o apply reclama que não achou o rascunho.
+
+## Guard de idempotência (`spec-wave:decomposed`)
+
+O evento `labeled` pode redisparar (re-add da label, retry de runner). Para não duplicar issues, o `decompose` **pula** quando a issue já tem `spec-wave:decomposed` **ou** já tem sub-issues do tipo-alvo (`[STORY]` para Feature, `[TASK]` para RFC). A label é gravada ao **aplicar**. Os workflows ainda usam `concurrency` por issue.
+
+A `spec-wave:decompose-ready` **não** entra nesse guard — é estado de rascunho pendente, não de decomposição feita.
+
+**Para forçar um re-decompose:**
+
+```bash
+gh issue edit <n> --remove-label "spec-wave:decomposed"
+```
+Depois **apague/feche as sub-issues antigas** (senão a detecção por sub-issues pula de novo), apague o `decomposition.md` se quiser um rascunho novo, e re-adicione `spec-wave:decompose`.
+
+## Dependências entre Stories
+
+O `decompose` grava `Depende de: #N, #M` no corpo das Stories e cria a relação nativa *blocked by*. Isso alimenta as skills **order** e **implement**. **Não apague essa linha** ao editar o corpo de uma Story; para mudar dependências, edite a linha (e/ou a relação *blocked by*).

package/src/plugin/skills/decompose/model-prompt.critique.md

@@ -0,0 +1,46 @@
+---
+name: critique-stories
+action: critique
+description: Critério da crítica adversarial das Stories propostas contra o spec.md e o plan.md, antes de virarem issues.
+tools: [Read, Glob, Grep]
+maxTurns: 20
+verifiers: 3
+lenses:
+  - "contradição — alguma story contradiz, inverte ou ignora um requisito da spec ou uma decisão do plan?"
+  - "critérios de aceite — os critérios embutidos nas stories são compatíveis com as regras de negócio da spec?"
+  - "cobertura e ordem — as stories cobrem a Feature inteira, e a ordem/dependências declaradas são executáveis?"
+---
+
+# Crítica adversarial das Stories
+
+Você audita as Stories propostas (JSON) contra o `spec.md` e o `plan.md` fornecidos. Seu papel é encontrar problemas, não elogiar.
+
+Procure stories que contradizem, invertem ou ignoram requisitos da spec ou decisões do plan, e critérios de aceite incompatíveis com as regras de negócio.
+
+Esta auditoria roda **antes de qualquer issue ser criada**. É a última chance de impedir que trabalho errado vire backlog.
+
+## O que caracteriza um achado
+
+- **Contradições diretas** entre as stories e a spec/plan.
+- **Inversões de requisito** — ex.: a spec exige consentimento ANTES de persistir e a story persiste antes de pedir consentimento.
+- **Violações de restrição explícita** — minimização de dados (LGPD), limites de retenção, campos proibidos.
+- **Critérios de aceite incompatíveis** com as regras de negócio da spec.
+- **Lacuna de cobertura** — um Critério de Aceite da spec que nenhuma story endereça.
+- **Dependência impossível** — `dependsOn` que aponta para uma story que entrega depois, ou ordem que exige o que ainda não existe.
+
+<!-- requires-tools -->
+## Como verificar
+
+Você tem `Read`, `Glob` e `Grep`. Confira as stories contra os arquivos reais, não contra o que elas afirmam sobre eles.
+<!-- /requires-tools -->
+## Barra de rigor
+
+NÃO invente problemas. Se as stories estiverem consistentes com spec e plan, diga isso — uma decomposição limpa é um resultado legítimo e frequente.
+
+O inverso também vale: "não consegui confirmar" é uma refutação, não uma aprovação.
+
+## Consequência
+
+Um achado marcado como **grave** **aborta** a decomposição: nenhuma story ou task é criada, a label `spec-wave:critique-failed` é aplicada e o trigger `spec-wave:decompose` é removido. Um achado **menor** é comentado na issue, e a decomposição segue.
+
+Ou seja: um achado grave seu cancela a criação de dezenas de issues. Reserve-o para contradição real, não para preferência de estilo.

package/src/plugin/skills/decompose/model-prompt.feature.md

@@ -0,0 +1,69 @@
+---
+name: decompose-feature
+action: decompose
+description: Decompõe uma Feature em Stories ordenadas, cada uma com suas Tasks técnicas.
+tools: [Read, Glob, Grep]
+maxTurns: 30
+json:
+  shape: '{"stories": [{"title": "...", "userStory": "...", "body": "...", "dependsOn": [0], "tasks": [{"title": "...", "body": "..."}]}]}'
+  retries: 1
+---
+
+# Decomposição de Feature em Stories
+
+Você é um Tech Lead experiente em decomposição de trabalho ágil. A partir da Feature fornecida (com spec.md e plan.md), gere uma lista de Stories e Tasks.
+
+## Entrada
+
+- Título e número da issue da Feature
+- O conteúdo de `spec.md` — critérios de aceite em Gherkin, fluxos, regras de negócio
+- O conteúdo de `plan.md` — estratégia técnica, matriz de rastreabilidade, detalhamento por camada
+
+Quando um dos dois documentos não existir, a entrada diz isso explicitamente. Decomponha com o que houver, mas não invente o que faltou.
+
+<!-- requires-tools -->
+## Exploração antes de decompor
+
+Você tem `Read`, `Glob` e `Grep` no repositório. Use-os para dimensionar as tasks contra o código que existe de verdade: uma task "criar endpoint X" é diferente conforme o controller já exista ou não. Ancore os títulos técnicos nos caminhos e nomes reais que encontrar.
+<!-- /requires-tools -->
+
+## Contrato de saída
+
+Responda APENAS com JSON válido neste formato:
+
+```json
+{
+  "stories": [
+    {
+      "title": "Título curto da story (apenas a parte 'quero', sem prefixo)",
+      "userStory": "Como <perfil>, quero <objetivo>, para <benefício>",
+      "body": "Descrição complementar da story com contexto e critérios de aceite relevantes",
+      "dependsOn": [0],
+      "tasks": [
+        {
+          "title": "Título técnico curto da task (sem prefixo)",
+          "body": "Descrição técnica detalhada"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Regras
+
+- `title` deve ser CURTO (máx. ~60 caracteres): apenas a parte "quero" da user story, sem o "Como" nem o "para", e sem prefixo. Ex.: "visualizar meus repositórios em layout responsivo"
+- `userStory` deve trazer a user story completa no formato "Como <perfil>, quero <objetivo>, para <benefício>"
+- `body` é texto complementar (contexto, critérios de aceite); não repita o título
+- Cada Story deve ter 2–5 Tasks associadas
+- Tasks devem ser atividades técnicas concretas, com `title` curto e `body` detalhado
+- Gere entre 3 e 7 Stories por Feature
+- Ordene as stories na sequência de implementação — a ORDEM da lista importa
+- `dependsOn` (opcional): índices 0-based das stories ANTERIORES na lista das quais esta story depende. Referencie apenas índices menores que o da própria story. Use `[]` quando a story puder ser feita em paralelo (sem dependências); se omitido, assume-se dependência da story anterior (sequencial)
+- Escreva títulos e corpos em português (pt-BR). Não use caracteres de outros alfabetos (CJK, cirílico, árabe, tailandês).
+
+## O que acontece com a sua saída
+
+Cada story vira uma issue `[STORY]` e cada task uma issue `[TASK]` vinculada como sub-issue, posicionadas na etapa **✅ Ready** do board. As dependências viram a relação nativa `blocked_by` do GitHub e uma linha "Depende de: #N" no corpo. Ou seja: a ordem e o `dependsOn` que você devolver determinam a ordem real de execução do time.
+
+Antes disso, uma crítica adversarial audita as stories contra a spec e o plan (ver a skill `critique-stories`). Achados graves cancelam a criação — nenhuma issue é aberta.

package/src/plugin/skills/decompose/model-prompt.rfc.md

@@ -0,0 +1,52 @@
+---
+name: decompose-rfc
+action: decompose
+description: Decompõe um RFC diretamente em Tasks técnicas, sem camada de Stories.
+tools: [Read, Glob, Grep]
+maxTurns: 30
+json:
+  shape: '{"tasks": [{"title": "...", "body": "..."}]}'
+  retries: 1
+---
+
+# Decomposição de RFC em Tasks
+
+Você é um Tech Lead experiente. A partir do RFC fornecido (proposta técnica/de processo), gere a lista de Tasks técnicas concretas necessárias para implementá-lo.
+
+Um RFC não passa por spec/plan — ele é a proposta em si. Por isso não há camada de Stories aqui: as tasks penduram direto no RFC.
+
+## Entrada
+
+- Título e número da issue do RFC
+- O corpo da issue, que é o texto da proposta
+
+<!-- requires-tools -->
+## Exploração antes de decompor
+
+Você tem `Read`, `Glob` e `Grep` no repositório. Um RFC quase sempre descreve mudança em algo que já existe — localize esse algo antes de listar tasks, e nomeie na `body` os arquivos e áreas que cada task vai tocar.
+<!-- /requires-tools -->
+## Contrato de saída
+
+Responda APENAS com JSON válido neste formato:
+
+```json
+{
+  "tasks": [
+    {
+      "title": "Título técnico curto da task (sem prefixo)",
+      "body": "Descrição técnica detalhada (o que fazer, áreas/arquivos afetados, critério de pronto)"
+    }
+  ]
+}
+```
+
+## Regras
+
+- `title` CURTO (máx. ~60 caracteres), sem prefixo.
+- `body` detalhado e acionável.
+- Gere entre 3 e 10 Tasks concretas que, juntas, cubram o RFC.
+- Escreva títulos e corpos em português (pt-BR). Não use caracteres de outros alfabetos (CJK, cirílico, árabe, tailandês).
+
+## O que acontece com a sua saída
+
+Cada task vira uma issue `[TASK]` vinculada como sub-issue do RFC e posicionada na etapa **✅ Ready** do board.

package/src/plugin/skills/doctor/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: spec-wave-doctor
+description: "Use como PRIMEIRO passo de troubleshooting do spec-wave: erro 404 ao criar issues, comando falhando sem motivo claro, board com colunas estranhas, Action que não roda, dúvida sobre token/escopos ou sobre qual modelo de IA está configurado. Também no início de uma sessão de trabalho. Gatilhos: 'spec-wave está com erro', 'não consigo criar issue', 'diagnosticar spec-wave', 'rodar o doctor'. Prefira esta skill a depurar gh api na mão."
+allowed-tools:
+  - Bash(npx @spec-wave/cli@latest *)
+  - Bash(gh auth status)
+  - Read
+---
+
+# spec-wave doctor — preflight de auth e configuração
+
+Comando **local**, sem flags:
+
+```bash
+npx @spec-wave/cli@latest doctor
+```
+
+## O que ele checa
+
+- **Token GitHub** e a fonte dele; **escopos** (`repo`, `project`, `workflow`), com degradação para checks funcionais em fine-grained PATs
+- **Conta ativa do `gh`** vs. o owner do repositório
+- **`.spec-wave.json`**: campos presentes e sincronia com o Project real
+- **Acesso ao repositório**
+- **Configuração de IA**: provider, modelo, `ai.models`, escalada da crítica, apelidos de modelo, teto de saída e os secrets do Actions
+- **Higiene do board e das labels**: colunas fora do fluxo canônico, labels `spec-wave:*` descontinuadas ou ausentes
+- **spec-kit**: `specKit.command` / env `SPEC_WAVE_IMPLEMENT_CMD` — se ausente, sugere exemplos por agente (Claude Code, opencode, Codex, Copilot CLI, Kiro CLI, Qwen Code)
+- **Workflows**: presença + **versão da CLI fixada** (não `@latest`)
+
+## Como ler a saída
+
+| Símbolo | Significado |
+|---------|-------------|
+| `✓` | ok |
+| `✗` | problema confirmado |
+| `!` | não verificável (best-effort — falha de rede nunca derruba o doctor) |
+
+**Exit 1** se houver algum `✗`.
+
+## Passos
+
+1. Rode o comando.
+2. Para cada `✗`, explique a causa ao usuário e proponha a correção concreta:
+   - escopo faltando → o usuário roda `!gh auth refresh --scopes project,repo,workflow` (interativo, ele executa)
+   - `.spec-wave.json` dessincronizado → `npx @spec-wave/cli@latest refresh --config`
+   - workflows/labels divergentes → skill **update**
+   - secret de IA ausente → Settings → Secrets → Actions (`ANTHROPIC_API_KEY` ou `OPENROUTER_API_KEY`)
+   - `specKit.command` ausente → configure antes de usar a skill **implement**
+3. Trate `!` como "não deu para verificar", não como falha.
+4. Se tudo passar e o problema original persistir, aí sim investigue a superfície específica (Action, issue, board).
+
+> **404 ao criar issues** é o caso clássico: quase sempre token sem acesso ao repo/org — e o doctor aponta exatamente isso.

package/src/plugin/skills/fix-pr/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: spec-wave-fix-pr
+description: "Use para auditar um Pull Request e corrigir os problemas encontrados — segurança, arquitetura, infraestrutura e qualidade — gerando um commit separado por fix, respondendo cada review comment com o hash do commit e postando um sumário no PR. Gatilhos: 'auditar o PR 42', 'corrigir os comentários de review', 'fix-pr 42', 'resolver os apontamentos do PR'."
+allowed-tools:
+  - Bash(gh pr *)
+  - Bash(gh api *)
+  - Bash(git add *)
+  - Bash(git commit *)
+  - Bash(git push *)
+  - Bash(git checkout *)
+  - Read
+  - Edit
+  - Glob
+  - Grep
+  - Agent
+---
+
+# spec-wave fix-pr — auditoria e correção de PR
+
+Cada fix vira um **commit separado** no branch do PR. Cada review comment recebe uma **resposta com o hash do commit**.
+
+**Pré-requisitos:** `.spec-wave.json` deve existir (para resolver `owner/repo`). Token com permissão de push no branch do PR.
+
+## Passos
+
+### 1. Resolver contexto
+
+Leia `.spec-wave.json` para obter `owner` e `repo`. Confirme o número do PR com o usuário se não vier como argumento.
+
+### 2. Coletar dados do PR
+
+```bash
+gh pr view <número> --json number,title,headRefName,body,changedFiles
+gh pr diff <número>
+gh api repos/<owner>/<repo>/pulls/<número>/comments
+gh api repos/<owner>/<repo>/pulls/<número>/reviews
+```
+
+Liste todos os arquivos alterados e colete os review comments (inline) e reviews gerais.
+
+### 3. Checkout do branch
+
+```bash
+gh pr checkout <número>
+```
+
+### 4. Varredura de problemas
+
+Para cada categoria, leia os arquivos alterados e identifique issues:
+
+| Categoria | O que procurar |
+|-----------|----------------|
+| **Segurança** | Credenciais hardcoded, secrets/API keys expostas, configs inseguras, injeção SQL/XSS |
+| **Arquitetura** | Dependências circulares, exports faltando, wiring incompleto, violações de camada |
+| **Infraestrutura** | OIDC mal configurado, IAM permissivo demais, Dockerfile sem usuário não-root, state remoto ausente |
+| **Qualidade** | sync-over-async, validação ausente, operações não idempotentes, error handling ausente |
+
+Se não houver review comments manuais, use um agente de review para detecção automatizada sobre o diff + arquivos alterados.
+
+### 5. Corrigir, um commit por problema
+
+Para cada problema: leia o arquivo (Read), aplique o fix (Edit), e commite isoladamente:
+
+```bash
+git add <arquivo>
+git commit -m "fix: <problema> (issue #<N>)
+
+<causa raiz>
+
+Solution: <descrição do fix>"
+git push
+```
+
+### 6. Responder aos review comments
+
+Para cada comment inline:
+
+```bash
+gh api repos/<owner>/<repo>/pulls/<número>/comments/<comment-id>/replies \
+  -f body="✅ **FIXED** — commit **<HASH>**
+
+\`\`\`<linguagem>
+<trecho corrigido>
+\`\`\`
+
+<explicação do fix>"
+```
+
+### 7. Sumário no PR
+
+```bash
+gh pr comment <número> --body "<sumário>"
+```
+
+Formato:
+
+```markdown
+## 🔍 PR Audit — Spec Wave
+
+### Problemas encontrados e corrigidos
+
+| # | Severidade | Categoria | Problema | Commit |
+|---|-----------|-----------|---------|--------|
+| 1 | 🔴 Critical | Segurança | Credencial hardcoded em config.js | abc1234 |
+| 2 | 🟡 Medium | Qualidade | Operação não idempotente em createOrder | def5678 |
+
+### Commits criados
+- `abc1234` fix: credencial hardcoded removida (issue #1)
+- `def5678` fix: idempotency key adicionada em createOrder (issue #2)
+
+**Total:** <N> problema(s) encontrado(s) e corrigido(s).
+```
+
+## Severidade
+
+| Nível | Critério |
+|-------|----------|
+| 🔴 Critical | Segurança, dados expostos, falha em produção |
+| 🟠 High | Bug que afeta usuários, arquitetura quebrada |
+| 🟡 Medium | Qualidade, manutenibilidade, performance |
+| 🔵 Low | Estilo, naming, comentários |
+
+## Output esperado
+
+- Lista de issues (severidade + impacto)
+- Lista de commits criados (hash + mensagem)
+- Confirmação das replies postadas nos review comments
+- Estado final do PR
+
+> Reporte fielmente: se um problema foi encontrado mas **não** corrigido (fora de escopo, exige decisão do usuário), diga isso explicitamente no sumário em vez de omitir.