jarvis-ai-framework 5.7.0 → 6.0.0

package/skills/eng-global-investigation/references/caso-investigar.md

@@ -0,0 +1,60 @@
+# Caso investigar
+
+O `/eng.debug` recebeu um **sintoma concreto**: chave ou URL do card, mensagem de erro, stack trace ou "X acontece quando Y". Aqui o objetivo é achar a causa de **um** bug e propor a correção, sem mexer em nada. Siga o método e a política de acesso do [`SKILL.md`](../SKILL.md).
+
+## 1. Coletar o sintoma
+
+- **Card:** se `TASK_MANAGER` estiver preenchido, leia o card no board (só leitura). Sem acesso, peça ao usuário para colar o conteúdo. Nunca comente no card.
+- Do card ou da mensagem, registre: título, passos para reproduzir, ambiente (local, staging, produção), serviços citados, identificador de correlação (correlation ID ou request ID) e logs ou stack trace anexados.
+- Pergunte só o que falta: identificador de correlação, frequência (sempre, às vezes, uma vez), mudança recente (deploy, feature flag, migração, infraestrutura), logs não anexados.
+
+## 2. Ler o código antes de levantar hipóteses
+
+Obrigatório: hipótese sem leitura de código é especulação.
+
+1. **Ponto de entrada:** com arquivo:linha no stack trace, leia ao redor dessa linha; só com a rota, a fila ou o nome da função, localize o handler buscando pelo nome nos repositórios do workspace.
+2. **Leia o fluxo:** quem recebe (handler, consumidor, job), quem processa (serviço, regra de negócio) e o ponto exato do erro (o que a linha faz e que estado espera).
+3. **O que procurar:**
+
+| O que procurar | Por que importa |
+|----------------|-----------------|
+| Tratamento de erro ausente ou genérico | Pode estar engolindo o erro real |
+| Chamada a outro serviço sem tempo limite | Bug intermitente por lentidão |
+| Operação assíncrona sem espera ou sem tratamento | Condição de corrida ou erro perdido |
+| Validação de entrada ausente | Dado inválido chegando na camada errada |
+| Dependência de estado externo (cache, banco, outro serviço) | Falha intermitente por estado inconsistente |
+| Identificador de correlação não repassado | Rastreio entre serviços vira trabalho manual |
+
+4. **Registre o que leu** (vai para "Código lido" do relatório): arquivo:linha, fluxo e o trecho mais suspeito (até 10 linhas). Sem acesso ao repositório, peça o trecho ao usuário.
+
+## 3. Hipóteses e cruzamento de serviços
+
+- Levante as hipóteses como diz o método do `SKILL.md`.
+- **Se o bug cruza serviços** (o usuário cita outro serviço; o stack trace tem URL de outro serviço, nome de fila ou erro de cliente HTTP; funciona isolado e falha no fluxo completo; falha intermitente que some na retentativa) **e** `eng-backend-microservices-trace` está registrada em `BACKEND_SPECIALIZATIONS`: chame-a com `{serviço-de-entrada} {sintoma-ou-chave}`. As hipóteses rankeadas do `ms-trace-report.md` substituem as suas, e a investigação segue pela fronteira de maior risco. Sem a especialização, aplique [`fronteiras-entre-componentes.md`](fronteiras-entre-componentes.md) à mão.
+
+## 4. Plano de investigação e evidências
+
+- Monte um plano incremental e seguro: logs e métricas a observar, consultas sem risco, testes que o usuário pode rodar. Diga sempre o que é só leitura e o que exigiria alterar código, configuração ou dados (e, então, em que ambiente, pela política de acesso).
+- A cada evidência, atualize as hipóteses (descartadas, fortalecidas). Ao convergir, explique o mecanismo do bug, por que não aparecia antes (se for o caso) e o impacto em outros fluxos.
+
+## 5. Correção proposta
+
+Só com evidência razoável:
+
+- Descreva a mudança, os componentes afetados e os testes para depois dela.
+- Correção arriscada: proponha uma alternativa mais conservadora, um contorno temporário e como fazer deploy e rollback.
+
+## 6. Próximo passo: `/eng.work` ou `/eng.plan`
+
+**Vá direto ao `/eng.work`** só se **tudo** for verdade: uma única correção clara, impacto cirúrgico (um arquivo, uma função), sem risco de efeito colateral, correção trivial (ex.: valor errado, condição invertida). Diga ao usuário que o `/eng.plan` está sendo pulado e por quê.
+
+**Passe pelo `/eng.plan`** se **qualquer** um for verdade: mais de uma abordagem com trade-offs; mais de um componente ou serviço; risco de regressão; causa com decisão de arquitetura; mudança de infraestrutura, banco ou configuração; categoria `BUG-CRÍTICO` ou `SEGURANÇA`. Neste caso, grave também `$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/architecture.md` no template `templates/engineering/architecture-template.md`, na forma curta do tipo `bugfix` (contexto, causa raiz, estado atual e proposto, componentes, riscos, testes) e com as alternativas de correção como **Questões em Aberto**. É esse arquivo que o `/eng.plan` exige.
+
+## 7. Relatório
+
+Grave `$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/debug-report.md` no template `templates/engineering/debug-report-template.md`, sempre, com qualquer veredito:
+
+- **Teste de regressão:** descreva, com a base `eng-qa` (tema 5, Automação de Testes) e a especialização de `QA_SPECIALIZATIONS`, se houver, o teste que reproduz o bug (falha antes da correção, passa depois, cobre o caso que causou o bug). Ele é escrito no `/eng.work`.
+- **Plano de validação:** testes antes do deploy, passos em staging, o que observar depois (logs com o identificador de correlação, métricas, alertas que deveriam ter disparado).
+- **Critério de resolvido:** comportamento confirmado nos passos de reprodução e sem nova ocorrência por 24h (P0), 48h (P1) ou 1 semana (P2).
+- **Débitos e melhorias:** observabilidade, tratamento de erro, tempo limite, retentativa, fila de falhas, identificador de correlação (regra de `eng-rules.md`), testes que teriam evitado o bug. Estruture cada um com a base `eng-qa` (tema 14, Gestão de Testes e de Defeitos) como **card pronto** (`DÉBITO-TÉCNICO P{0-3}`, vinculado ao `{TASK_MANAGER_KEY}`). Separe o que entra na correção atual do que fica para depois.

package/skills/eng-global-investigation/references/caso-varrer.md

@@ -0,0 +1,67 @@
+# Caso varrer
+
+O `/eng.debug` recebeu um **escopo sem sintoma**: pasta, módulo, `--all` ou um pedido como "quais os riscos de…". Aqui o objetivo é achar **suspeitos** (bugs latentes, falhas de segurança, problemas de performance, débito técnico) e priorizá-los, sem mexer em nada. Siga a política de acesso do [`SKILL.md`](../SKILL.md). Usos típicos: entrar num projeto legado, revisão depois de um incidente, check-up periódico, preparação para um refactor grande ou análise de risco antes de uma mudança crítica.
+
+## 1. Escopo
+
+- Confirme o escopo: pasta, módulo, `--all` (todos os repositórios do workspace; em `WORKSPACE_MODE=workspace`, só as subpastas com `.git/`, sem a pasta da IDE, `.jarvis/`, `.vscode/` e `node_modules/`).
+- Se não estiver claro, pergunte (uma pergunta por vez): o propósito do módulo, as áreas críticas (autenticação, pagamentos, dados sensíveis), áreas com problemas conhecidos e a prioridade (bugs funcionais, performance, segurança).
+- Identifique a stack pelos manifestos (`package.json`, `pyproject.toml`, `go.mod`, `pom.xml`…) e pelo `CDD-MIND-MAP.md`, e aplique a regra de especializações da área.
+
+## 2. Sequência ou paralelo
+
+Conte os arquivos de código do escopo (sem dependências instaladas nem arquivos gerados). Com `--all` **ou mais de 200 arquivos**, pergunte com `AskUserQuestion`: **"Varrer em sequência ou em paralelo?"** — **Em sequência (padrão)** / **Em paralelo** (mais rápido; um subagente por categoria, no máximo 4; custo maior em tokens). Abaixo disso, varra em sequência sem perguntar. Em paralelo, cada subagente recebe o escopo, uma categoria e esta política de acesso, e só lê.
+
+## 3. Verificações locais
+
+Teste e lint locais rodam livres (política de acesso): use os comandos que o **projeto já define** (scripts do manifesto, `Makefile`), sem instalar nada. Sem comando definido, registre "não configurado" no relatório. Nada que altere estado, e nada em produção.
+
+## 4. O que procurar
+
+Busque por padrão de risco, na linguagem do projeto, e confirme cada achado lendo o trecho (achado não lido não entra):
+
+| Categoria | Sinais |
+|-----------|--------|
+| Bugs funcionais | tratamento de erro vazio ou genérico; comparação frouxa onde a linguagem distingue; variável usada antes de ter valor; log de depuração esquecido em código de produção |
+| Code smells | funções ou arquivos muito grandes; duplicação; acoplamento alto; complexidade alta |
+| Segurança | consulta ou comando montado concatenando entrada; HTML montado com entrada sem sanitizar; segredo no código; endpoint sem autenticação |
+| Performance | consultas dentro de laços (N+1); listas sem paginação; laços aninhados sobre dados grandes; recursos abertos sem fechar ou ouvintes sem remover |
+| Débito técnico | TODO, FIXME e HACK; código comentado; dependências desatualizadas ou com vulnerabilidade conhecida (pela ferramenta do projeto) |
+| Arquitetura | separação de responsabilidades, estrutura de pastas, modularidade, consistência de padrões |
+
+## 5. Classificar e priorizar
+
+| Categoria | Descrição |
+|-----------|-----------|
+| `BUG-CRÍTICO` | Afeta produção, segurança ou causa perda de dados |
+| `BUG-ALTO` | Quebra funcionalidade importante |
+| `BUG-MÉDIO` | Comportamento inesperado não crítico |
+| `BUG-BAIXO` | Caso de borda, problema visual menor |
+| `CODE-SMELL` | Código difícil de manter |
+| `DÉBITO-TÉCNICO` | Código desatualizado, falta de testes |
+| `SEGURANÇA` | Vulnerabilidade potencial |
+| `PERFORMANCE` | Lentidão ou uso excessivo de recursos |
+
+**Severidade** = impacto × probabilidade × esforço de correção (cada um de 1 a 5).
+
+| Prioridade | Critério |
+|------------|----------|
+| P0 | Severidade ≥ 60, `BUG-CRÍTICO` ou `SEGURANÇA` |
+| P1 | Severidade ≥ 40, `BUG-ALTO` |
+| P2 | Severidade ≥ 20, `BUG-MÉDIO` ou `CODE-SMELL` |
+| P3 | Severidade < 20, `BUG-BAIXO` ou `DÉBITO-TÉCNICO` |
+
+Não relate falso positivo sem validar, nem severidade sem análise. Com mais de 100 suspeitos, detalhe P0 e P1 e liste o resto num anexo, sugerindo varrer por áreas.
+
+## 6. Relatório
+
+Grave o relatório no template `templates/engineering/bug-audit-report-template.md`:
+
+- com chave: `$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/bug-audit-report.md`;
+- sem chave: calcule **uma vez** o nome `bug-audit-{AAAAMMDD-HHMMSS}`, guarde-o e use-o em todos os arquivos e na mensagem final: `$SESSIONS_DIR/eng/{nome}/bug-audit-report.md`.
+
+Cada suspeito P0 e P1 (e os demais, se o usuário pedir) traz o **card pronto**, estruturado com a base `eng-qa` (tema 14, Gestão de Testes e de Defeitos): título, tipo, prioridade, labels, comportamento atual × esperado, localização, impacto e sugestão de correção. O comando **não abre** os cards.
+
+## 7. Depois do relatório
+
+Ofereça com `AskUserQuestion` investigar um suspeito (os P0 primeiro): o escolhido segue no [caso investigar](caso-investigar.md), no mesmo comando, e ganha o próprio `debug-report.md`. Sugira abrir os cards P0 e P1 no board e priorizar os P2 e P3 no backlog.

package/skills/eng-global-investigation/references/fronteiras-entre-componentes.md

@@ -0,0 +1,36 @@
+# Fronteiras entre componentes
+
+Quando o sistema tem várias partes encadeadas, o bug costuma estar numa **fronteira**: um componente entrega algo diferente do que o seguinte espera. Antes de propor correção, descubra **qual** fronteira falha.
+
+## Exemplos de fronteira
+
+| Cadeia | Fronteiras |
+|--------|------------|
+| Serviço A → HTTP → Serviço B | requisição que sai de A; requisição que chega em B; resposta de volta |
+| Produtor → fila → consumidor | mensagem publicada; mensagem consumida; o que acontece quando o consumo falha |
+| Pipeline de CI → build → deploy | variáveis e segredos disponíveis em cada etapa; artefato gerado; artefato publicado |
+| Interface → API → banco | dado enviado; dado validado; dado gravado |
+
+## Passo a passo
+
+1. **Desenhe a cadeia** do fluxo afetado, do ponto de entrada ao ponto em que o sintoma aparece. Use o código, não a memória: ache quem chama quem (rotas, clientes HTTP, publicação e consumo de mensagens, etapas do pipeline).
+2. **Para cada fronteira, confira:**
+   - o formato do que sai e do que chega (campos, tipos, nomes, versão do contrato);
+   - se a configuração e o ambiente chegam iguais dos dois lados (URL, variável, segredo, fuso, idioma);
+   - o que acontece em erro, demora ou falta de resposta (tempo limite, retentativa, fila de falhas, erro engolido);
+   - se o identificador de correlação passa adiante (é ele que liga os registros dos dois lados).
+3. **Junte evidência de onde quebra.** Pela leitura, compare o contrato dos dois lados. No ambiente local, se preciso, registre o que entra e sai em cada fronteira e rode uma vez (política de acesso do `SKILL.md`). Em produção, só leitura: logs e métricas que já existem.
+4. **Investigue só a fronteira que falha.** Com ela identificada, volte às hipóteses do `SKILL.md`.
+
+## Sinais típicos
+
+| Sinal | Fronteira suspeita |
+|-------|--------------------|
+| Funciona isolado, falha no fluxo completo | contrato ou configuração entre os componentes |
+| Falha intermitente que some na retentativa | tempo limite, concorrência, estado compartilhado |
+| "Não chega" sem erro | erro engolido ou mensagem descartada sem fila de falhas |
+| Funciona local, falha no pipeline | variável, segredo ou versão diferente no ambiente |
+
+## Quando há muitos serviços
+
+Se o fluxo cruza microsserviços (HTTP e mensageria) e a especialização `eng-backend-microservices-trace` está registrada em `BACKEND_SPECIALIZATIONS`, o caso investigar do `/eng.debug` a usa para mapear a cadeia e rankear as hipóteses por fronteira.

package/skills/eng-global-investigation/references/rastrear-para-tras.md

@@ -0,0 +1,34 @@
+# Rastrear para trás
+
+Quando o erro aparece fundo na pilha, corrigir onde ele explode trata o sintoma. A causa está onde o valor ruim **nasceu**. Esta técnica segue o valor de volta, chamada por chamada, até a origem.
+
+## Quando usar
+
+- O erro acontece longe de onde o dado entrou (ex.: "valor vazio" ao gravar, mas o valor veio de três chamadas antes).
+- Um valor inválido (vazio, nulo, no formato errado) chega a uma função que não deveria recebê-lo.
+- Não está claro qual caminho do código levou até o erro.
+
+## Passo a passo
+
+1. **Observe o sintoma.** Anote a mensagem e o ponto exato (arquivo:linha) onde o erro aparece.
+2. **Ache a causa imediata.** Qual linha produziu o erro e com qual valor? Ex.: `salvar(registro)` falha porque `registro.id` está vazio.
+3. **Pergunte: quem chamou isto com esse valor?** Leia quem chama a função e de onde vem o argumento.
+4. **Continue subindo.** Repita a pergunta a cada nível até achar o ponto em que o valor deixou de ser válido, ou em que nunca foi validado.
+5. **Ache o gatilho original.** É ali que a correção vale: na origem, não no sintoma.
+
+```
+salvar(registro)              ← erro: id vazio
+  ← montarRegistro(entrada)   ← id copiado de entrada.id
+    ← lerEntrada(requisicao)  ← entrada.id nunca preenchido quando o campo vem com outro nome
+                                 ↑ gatilho original: corrigir aqui
+```
+
+## Quando não dá para seguir pela leitura
+
+Se não for possível descobrir quem chamou só lendo o código, **no ambiente local** acrescente um registro temporário logo antes do ponto do erro, com o valor recebido e a pilha de chamadas (o recurso equivalente da linguagem). Rode uma vez, leia a saída e remova o registro. Em produção, não altere nada: peça os logs que já existem (política de acesso do `SKILL.md`).
+
+## Depois de achar a origem
+
+- Corrija na origem.
+- Considere validar também nas camadas por onde o valor passa (entrada, regra de negócio, gravação), para o mesmo erro não voltar por outro caminho.
+- Descreva no relatório o caminho percorrido (do sintoma até a origem): é a evidência do veredito.

package/templates/engineering/bug-audit-report-template.md

@@ -0,0 +1,81 @@
+---
+# Card ou número de controle, se houver; sem chave, o nome da pasta da sessão.
+task_key: {TASK-123 | bug-audit-AAAAMMDD-HHMMSS}
+
+# Data da varredura (YYYY-MM-DD).
+created_at: {YYYY-MM-DD}
+
+# Escopo varrido: pasta, módulo ou --all.
+escopo: {escopo}
+
+# Como a varredura rodou. Opções: sequência | paralelo (com o número de subagentes)
+execucao: {sequência | paralelo (N subagentes)}
+---
+
+# Varredura: {escopo}
+
+> Relatório do `/eng.debug` (caso varrer). Fica na sessão; o comando não abre nem comenta card. Cada suspeito traz o card pronto para o usuário abrir.
+
+## Resumo
+
+- **Suspeitos:** {N} — P0: {N} · P1: {N} · P2: {N} · P3: {N}
+- **Por categoria:** BUG-CRÍTICO {N} · BUG-ALTO {N} · BUG-MÉDIO {N} · BUG-BAIXO {N} · CODE-SMELL {N} · DÉBITO-TÉCNICO {N} · SEGURANÇA {N} · PERFORMANCE {N}
+- **Verificações locais:** lint {ok | n problemas | não configurado} · testes {ok | n falhando | não configurados}
+- **Fora do escopo ou não analisado:** {o que ficou de fora e por quê}
+
+## Suspeitos por prioridade
+
+> Um suspeito é um problema provável, ainda não confirmado como bug. Para confirmar, investigue-o com o `/eng.debug` (caso investigar).
+
+### P0 — ação imediata
+
+#### {n}. {título}
+
+- **Categoria:** {BUG-CRÍTICO | SEGURANÇA | …}
+- **Localização:** `{arquivo}:{linha}`
+- **O que foi visto:** {trecho ou padrão encontrado}
+- **Impacto:** {no usuário ou no negócio}
+- **Sugestão de correção:** {como corrigir}
+
+**Card pronto:**
+
+```
+Título: {título claro}
+Tipo: {Bug | Task | Security}
+Prioridade: P0
+Labels: bug-audit, {categoria}
+Descrição:
+  Comportamento atual: {…}
+  Comportamento esperado: {…}
+  Localização: {arquivo}:{linha}
+  Impacto: {…}
+  Sugestão de correção: {…}
+```
+
+### P1 — próxima sprint
+
+{mesma estrutura}
+
+### P2 — backlog
+
+{mesma estrutura}
+
+### P3 — débito técnico
+
+{mesma estrutura}
+
+## Áreas de risco
+
+- **Áreas críticas sem testes:** {área}: {motivo}
+- **Código complexo:** `{arquivo}`: {sinal}
+- **Dependências com problema conhecido:** {dependência, versão atual, versão segura}
+
+## Recomendações
+
+- **Curto prazo (1–2 sprints):** {…}
+- **Médio prazo (3–6 meses):** {…}
+- **Prevenção:** {testes, observabilidade, regras de lint, hooks}
+
+## Próximo passo
+
+{Investigar o suspeito {n} com o `/eng.debug` (caso investigar) | abrir os cards P0 e P1 no board | nova varredura em {área}}

package/templates/engineering/debug-report-template.md

@@ -0,0 +1,95 @@
+---
+# Card ou número de controle da tarefa (TASK_MANAGER do ENV.md; freelance = número de controle).
+task_key: {TASK-123}
+
+# Data em que a investigação foi feita (YYYY-MM-DD).
+created_at: {YYYY-MM-DD}
+
+# O que o usuário passou ao /eng.debug: chave ou URL do card, mensagem de erro, stack trace ou descrição.
+entrada: {entrada}
+
+# Veredito da investigação (skill eng-global-investigation). Opções: confirmado | provável | inconclusivo
+veredito: {confirmado | provável | inconclusivo}
+
+# Etapas usadas do orçamento pela urgência do context.md (alta 5 | normal 10 | baixa 15).
+orcamento: {usadas}/{teto}
+---
+
+# Investigação: {título curto do bug}
+
+> Relatório do `/eng.debug` (caso investigar). Fica na sessão; nada daqui é publicado no card.
+
+## Sintoma
+
+{O que acontece, o que era esperado e em que condição. Ambiente (local, staging, produção), frequência (sempre, às vezes, uma vez) e mudança recente, se houver.}
+
+**Reprodução:**
+
+1. {passo}
+2. {passo}
+
+{Se não foi reproduzido: o que falta para reproduzir.}
+
+## Código lido
+
+| Arquivo:linha | O que faz | O que chamou atenção |
+|---------------|-----------|----------------------|
+| `{caminho}:{linha}` | {papel no fluxo} | {observação} |
+
+**Fluxo lido:** {entrada} → {camada} → {dependências}
+
+## Hipóteses
+
+| # | Hipótese | Evidência (trecho lido) | Como confirmar ou descartar | Situação |
+|---|----------|-------------------------|-----------------------------|----------|
+| 1 | {causa provável e por quê} | `{arquivo}:{linha}` | {verificação} | {confirmada \| descartada \| aberta} |
+
+## Evidências
+
+{O que foi verificado e o resultado: leitura, reprodução, logs ou métricas (produção só leitura). Inclua o caminho do sintoma até a origem, quando houver.}
+
+## Veredito
+
+**{confirmado | provável | inconclusivo}** — {causa em uma ou duas frases}
+
+{Passe crítico: o que poderia derrubar esta conclusão e por que ela se mantém (ou por que foi rebaixada).}
+
+## Correção proposta
+
+**Preferida:** {mudança, arquivos e componentes afetados}
+
+**Alternativas** (se houver): {alternativa e trade-off}
+
+**Risco:** {regressão, migração, performance, segurança}
+
+## Teste de regressão
+
+{Teste que reproduz o bug: deve falhar antes da correção e passar depois, cobrindo o caso específico que causou o bug. Descrito aqui e escrito no `/eng.work`, no framework de testes do projeto.}
+
+## Plano de validação
+
+- **Antes do deploy:** {testes do fluxo afetado}
+- **Em staging:** {passos de reprodução}
+- **Depois do deploy:** {logs, métricas e alertas a observar}
+
+## Critério de resolvido
+
+Comportamento esperado confirmado nos passos de reprodução e sem nova ocorrência por **{24h (P0) | 48h (P1) | 1 semana (P2)}**.
+
+## Débitos e melhorias
+
+Cards prontos para o usuário abrir no board (o comando não abre card):
+
+### {título do card}
+
+- **Tipo:** {Bug | Task | Security}
+- **Prioridade:** {P0 | P1 | P2 | P3}
+- **Localização:** `{arquivo}:{linha}`
+- **Comportamento atual:** {…}
+- **Comportamento esperado:** {…}
+- **Ambiente:** {…}
+- **Vinculado a:** {TASK-123}
+
+## Próximo passo
+
+{`/eng.work {TASK-123}` (correção trivial: um arquivo, sem alternativa) | `/eng.plan {TASK-123}` (alternativas ou risco; o `architecture.md` curto foi gravado na sessão) | coletar mais dados: {quais}}

package/workflows/README.md

@@ -30,8 +30,7 @@ workflows/
     ├── eng.pre-pr.md             # Validação pré-PR
     ├── eng.pr.md                 # Criação de PR
     ├── eng.review.md             # Revisão
-    ├── eng.debug.md              # Debug/incident
-    ├── eng.bug-audit.md          # Auditoria de bugs
+    ├── eng.debug.md              # Debug: investiga um bug ou varre um escopo
     ├── eng.docs.md               # Documentação (engenharia)
     ├── eng.create-ard.md         # Criar ARD
     ├── eng.create-ard-from-code.md
@@ -88,14 +87,13 @@ workflows/
 | `eng.pre-pr.md` | Validação final antes do PR |
 | `eng.pr.md` | Criar branch, commit e Pull Request |
 | `eng.review.md` | Revisão de solução/PR |
-| `eng.debug.md` | Debug e investigação de incidentes |
+| `eng.debug.md` | Investiga um bug ou varre um escopo atrás de problemas |
 | `eng.docs.md` | Atualizar documentação de engenharia |
 | `eng.create-ard.md` | Criar ARD (Architecture Review Document) |
 | `eng.create-ard-from-code.md` | Criar ARD a partir do código |
 | `eng.create-rfc.md` | Criar RFC (Request For Comments) |
 | `eng.build-tech-spec.md` | Criar especificação técnica |
 | `eng.breakdown-subtasks.md` | Quebrar tech spec em subtarefas |
-| `eng.bug-audit.md` | Auditoria e análise de bugs |
 | `eng.light-arch.md` | Design arquitetural leve |
 | `eng.rpa.robot.md` | Criar robô novo ou manter existente — análise, scaffolding, impl, docs, PR |
 | `eng.frontend-component.md` | Criar ou refatorar componente frontend com qualidade (design system vs remote, a11y, testes) |