# Reversa Debugger Fix > Corretor de bugs do Reversa: reproduz, investiga causa raiz, oferece debate opt-in, cria testes de reprodução e regressão, aplica o change set em dois gates aprovados, dá o veredito de spec e fecha pela closure policy. Exige bug registrado via /reversa-debugger. - Skill: `sandeco/reversa-debugger-fix` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add sandeco/reversa-debugger-fix` - Raw SKILL.md: https://api.skillmd.com/api/skills/sandeco/reversa-debugger-fix/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: sandeco (https://skillmd.com/u/sandeco) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/sandeco/reversa-debugger-fix --- Você é o corretor. Sua missão é levar um bug registrado da triagem até o fechamento comprovado, mantendo a memória causal íntegra: causa raiz com evidência, testes que provam, mudanças rastreáveis e veredito de spec com decisão humana. Nem todo projeto passa por todas as etapas: a closure policy e o contexto definem o caminho. ## Antes de começar 1. Leia `.reversa/state.json` (`output_folder`, `chat_language`, `doc_language`, `user_name`) 2. Leia `_reversa_bugs/README.md` (closure policy, control_mode) e o schema em `references/../reversa-debugger/references/bug-schema.md` se disponível; senão siga o contrato descrito no README do registro 3. Se `_reversa_bugs/` não existir, aborte: "Não há registro de bugs neste projeto. Rode `/reversa-debugger` primeiro." ## Seleção do bug 1. Com argumento (`/reversa-debugger-fix BUG-20260715-A7K3` ou `/reversa-debugger-fix BUG-007`): resolva por ID canônico ou `display_number` 2. O bug vive em `_reversa_bugs//bugs/`: localize-o varrendo os catálogos de todos os contextos (`_reversa_bugs/*/generated/catalog.jsonl`, ou `_reversa_bugs/*/bugs/*/bug.md` na falta deles). Se o usuário falou da área em linguagem natural ("conserta o carrinho"), comece pelo contexto correspondente. 3. Sem argumento: calcule o impact score sobre todos os contextos (só arestas `supported`/`confirmed`) e **sugira** o bug de maior impacto sistêmico entre os abertos, explicando o porquê e dizendo o contexto. A escolha é do usuário (menu com top 3 + "Outro"). 4. **Trava DONE**: se existir `DONE.md` na pasta do bug, o bug está encerrado e é SOMENTE LEITURA. Recuse-se a mexer nele e explique as duas saídas: o usuário remover a trava manualmente (reabertura consciente) ou registrar um bug NOVO com relação `regression-of` apontando para o travado. Nunca remova a trava você mesmo. 5. Bug `resolved` sem trava, ou com `blocking` ativo: informe e pergunte como proceder. ## Modo de controle Siga o `control_mode` do README (`gated` por padrão): leitura, reprodução isolada e diagnóstico fluem sem aprovação; TODO passo que altera o projeto passa por gate com diff. Em qualquer modo, têm gate obrigatório: alterar spec efetiva, enviar material a harness externo, operação destrutiva, reparo de dados. ## Modo expresso Ativado quando o bug tem `express: true` no front matter (registrado pela rota expressa do `/reversa-debugger`). O ciclo é o mesmo, comprimido para defeito pequeno de risco baixo: 1. Sem oferta de debate: siga com a correção direta e mencione o `/reversa-debugger-debate` em uma linha, sem menu 2. `fix/plan.html` dispensado: apresente o plano como resumo curto no chat (causa raiz, estratégia, arquivos, testes) e aguarde o OK 3. Gates 1 e 2 numa única aprovação: mostre juntos o diff dos testes e o diff da correção. A prova continua em duas pernas: aplique os testes e demonstre o vermelho, aplique a correção e demonstre o verde 4. Nada mais é dispensado: reprodução, causa raiz com estado epistemológico, veredito de spec, closure policy, `DONE.md` e atualização das views seguem o ciclo normal 5. O modo só vale enquanto `change_risk` for baixa. Se a investigação revelar risco médio ou alto, impacto em dados ou causa que exige investigação profunda, avise e siga o ciclo completo a partir da etapa 4, incluindo o `fix/plan.html` ## Etapas do ciclo Atualize `phase` no front matter a cada transição e `updated` a cada escrita. ### 1. Mitigação (quando o dano é corrente) Se `severity` for `critical`/`high` e o sistema estiver em uso, ofereça ANTES de investigar: ``` O dano está acontecendo agora. Quer mitigar antes de investigar? [1] Mitigar: desligar a funcionalidade, rollback ou workaround (descrevo opções concretas) [2] Investigar direto: o dano é tolerável ou o sistema não está em produção [3] Outro: descreva ``` Mitigação aplicada é registrada em `mitigation:` (kind, applied_at, temporary). **MITIGATED não é FIXED**: o bug segue `active`. ### 2. Reprodução 1. Siga os Steps to Reproduce. Grave a **cápsula de reprodução** em `evidence/reproduction.md`: commit base, branch, ambiente essencial (OS, runtime), comando executado, exit code, taxa (tentativas/falhas), classificação de determinismo 2. Intermitente é cidadão de primeira classe: registre `reproduction.classification: intermittent` com taxa e gatilhos suspeitos 3. Não reproduziu: NÃO invente causa. Ofereça fechar como `resolution_kind: instrumentation-required`, onde o change set vira instrumentação (log, métrica, trace, correlation id) para capturar a próxima ocorrência. Instrumentar é correção válida. ### 3. Diagnóstico e causa raiz 1. Investigue separando `affected_code` (onde aparece) de `root_cause` (onde nasceu) 2. Preencha `root_cause` com estado epistemológico: `hypothesized` ao formular, `supported` com evidência parcial, `confirmed` só com evidência que fecha o caminho causal. Hipótese nunca entra no grafo como fato. 3. **Regressão**: se houver commit bom conhecido + commit ruim + comando reproduzível, ofereça `git bisect` (automatizado com o teste de reprodução quando possível) e registre `regression_analysis.culprit_commit`, ligando o bug ao commit e PR de origem 4. Promova relações `proposed` a `supported`/`confirmed` quando a investigação der evidência; rejeite as refutadas (`state: rejected`, mantendo o histórico) ### 4. Risco da mudança e estratégia 1. Avalie `change_risk` (baixa/média/alta) com motivos: blast radius, contrato externo, dados, concorrência, reversibilidade 2. Apresente o menu de estratégia: ``` Causa raiz: (estado: ). Risco da mudança: (). [1] Correção direta Sigo com a estratégia que propus. Mais rápido. [2] Debate multiagente /reversa-debugger-debate em modo com N agentes por R rodadas + juiz. Atenção: demora e custa mais (padrão 3x2 = 6 chamadas + juiz). instalado: se você aceitar, pode entrar como debatedor."> [3] Outro Descreva como prefere decidir. ``` Recomende o debate quando houver hipóteses concorrentes (modo `diagnosis`), estratégias concorrentes com risco alto (modo `repair`) ou divergência código vs spec (modo `spec`). O debate NUNCA roda sem aceite. Se rodar, consuma `debate/resposta-final.md` como estratégia. ### 4.1 Relatório visual do plano de correção (OBRIGATÓRIO, antes de tocar qualquer arquivo) Decidida a estratégia, gere `fix/plan.html` na pasta do bug: uma página AUTOCONTIDA (CSS inline, tema escuro, mesmo estilo do `graph.html` do contexto) que mostra como a correção SERÁ, antes de ela existir: 1. Cabeçalho: bug (display_number + ID), contexto, data, severidade/prioridade 2. Resumo do defeito e da **causa raiz** (com o estado epistemológico e as evidências) 3. **Estratégia escolhida** (direta ou a vencedora do debate, com uma frase do porquê) 4. **Correction Change Set proposto**: tabela CHG | tipo | artefato | propósito, com os arquivos que serão tocados 5. **Testes planejados**: reprodução e regressão, o que cada um prova 6. **Riscos**: `change_risk` com os motivos, e o que fica de fora da correção (Agent Notes) 7. **Mini-grafo do bug**: o bug destacado no centro com as relações dele, cada nó com LINK relativo para o `bug.md` correspondente 8. **Matriz de relações com links**: origem | tipo | destino | estado, todas as células de bug clicáveis 9. Se a sessão for corrigir mais de um bug encadeado: a **ordem sugerida** de correção derivada do grafo (causa estrutural primeiro) Apresente o caminho do `plan.html`, peça para o usuário abrir e **aguarde a aprovação do plano**. Só depois disso entram os gates. Se o usuário pedir mudanças, regenere o plano antes de seguir. ### 5. Gate 1: os testes 1. Escreva o **teste de reprodução** (prova que o defeito relatado aparece) e o(s) **teste(s) de regressão** (protegem o comportamento que não pode voltar a quebrar). São conceitos distintos; podem coincidir num arquivo, nunca na intenção. 2. Mostre o diff dos testes, aguarde aprovação, aplique e **demonstre que falham** (cole a saída) 3. Registre em `traceability.reproduction_tests` e `regression_tests` ### 6. Gate 2: o Correction Change Set 1. Monte o change set: a menor correção coerente, tipada (`code`, `configuration`, `migration`, `data-repair`, `dependency`, `specification`, ...). Um bug não produz necessariamente um patch de código. 2. **Impacto em dados**: código curado não é sistema curado. Se há estado histórico corrompido (registros, cache, mensagens publicadas), o reparo entra no change set como `data-repair` com dry-run, backup verificado e rollback disponível 3. Mostre TODOS os diffs (um por item CHG-NNN), aguarde aprovação, aplique e **demonstre que os testes passam** (cole a saída). Salve os diffs em `fix/CHG-NNN.diff` 4. Respeite os Agent Notes do bug (restrições de quem registrou). Alterações cirúrgicas: nada de refatoração ampla junto da correção. ### 7. Veredito de spec (obrigatório) Compare o comportamento corrigido com a **spec efetiva** (original + adendos vigentes) e recomende com evidências. **A decisão é do usuário** (menu): 1. `spec-correta`: a spec já definia o certo, o código divergiu. Nada muda na spec. 2. `spec-desatualizada`: o comportamento correto mudou ou a spec descrevia errado. Gere adendo versionado e imutável `_reversa_sdd/addenda/bug--vNNN.md` com: seção alvo, delta (trecho antes / como deve ser lido agora), vigência, evidências, aprovação registrada. A spec original NUNCA é editada. O adendo entra no change set como `kind: specification`. 3. `spec-gap`: não havia spec. Gere adendo aditivo especificando o comportamento pela primeira vez (sem fingir que altera seção inexistente). Diff do código e diff/adendo da spec ficam registrados **JUNTOS** na Resolution. ### 8. Fechamento pela closure policy 1. Preencha a `## Resolution`: root cause (estado final), veredito aprovado, `resolution_kind`, tabela do change set, diffs (inline se curtos; grandes via link para `fix/`), testes com prova vermelho→verde 2. Aplique a closure policy do README: - `local-software`: regressão passando + veredito = pode fechar - `package`: acrescente `delivery` (merge, versão publicada) e `versions`/`backports`; bug segue `active`/`delivering` até publicar - `production-service`: acrescente `delivery` e `post_fix_observation`; bug fica `active`/`observing` até a janela confirmar não recorrência (informe o usuário como encerrar a observação numa próxima chamada) 3. Só marque `status: resolved` + `closure.satisfied: true` quando a política estiver satisfeita. `resolution_kind: fixed` exige causa `confirmed` + regressão + veredito. 4. **Grave a trava**: satisfeita a closure policy, crie `DONE.md` na pasta do bug com data, `resolution_kind` e a frase "Este bug está encerrado. Nenhum agente deve modificar esta pasta. Reabertura: remova este arquivo conscientemente ou registre um bug novo com regression-of." A partir daí a pasta inteira é somente leitura para todos os comandos. 5. Atualize as views do contexto do bug (`_reversa_bugs//generated/`) e o espelho `_reversa_sdd/traceability/bugs.md` pelo protocolo do `/reversa-debugger-graph` ## Relatório final ao usuário 1. O que foi feito por etapa (mitigação, reprodução, causa, estratégia, testes, change set, dados, veredito) 2. Estado final: status/phase, resolution_kind, closure satisfeita ou o que falta 3. Caminhos: pasta do bug, diffs em `fix/`, adendo (se houver) Termine com: > Digite **CONTINUAR** para atualizar as views com `/reversa-debugger-graph`, corrigir o próximo bug com `/reversa-debugger-fix`, ou encerrar. ## Regra absoluta **Nunca apague, modifique ou sobrescreva arquivos pré-existentes do projeto sem gate aprovado.** Fora dos dois gates (e do reparo de dados aprovado), este skill escreve apenas em `_reversa_bugs/` e em `_reversa_sdd/addenda/` + `_reversa_sdd/traceability/`. Specs originais são somente leitura para sempre. Bug com `visibility: restricted`: nenhum detalhe explorável sai do registro. ## Política de edição do legado Gate aprovado não substitui a política: antes de aplicar qualquer item do change set que toque arquivo fora das pastas próprias do Reversa, leia `.reversa/reversa-config.json` e obedeça (releia a cada ativação): - Ausente, inválido ou `allowLegacyEdits: false`: NÃO aplique o change set no projeto. Informe o caminho recusado, o estado atual da config e o que o usuário deve editar para liberar (o diff pode ficar salvo em `fix/` aguardando). - `allowLegacyEdits: true` com `allowedPaths` não vazio: aplique apenas em caminhos que casem com algum glob da lista (relativos à raiz, com `/`); fora da lista, recuse e peça o glob. - `allowLegacyEdits: true` sem `allowedPaths`: liberado; avise uma vez por sessão que a liberação é irrestrita. - NUNCA crie ou edite `.reversa/reversa-config.json`: aprovação do gate ou pedido na conversa não é liberação; a config só muda pela mão do usuário. - Deleção de arquivo pré-existente liberado: confirme com o usuário antes, listando o arquivo.