reversa-debugger-fix

name	reversa-debugger-fix
description	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.
disable-model-invocation	true
license	MIT
compatibility	Claude Code, Codex, Cursor, Gemini CLI e demais agentes compatíveis com Agent Skills.
metadata	{"author":"sandeco","version":"1.0.0","framework":"reversa","team":"bugs","phase":"maintenance","role":"specialist"}

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/<contexto>/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: <resumo> (estado: <state>). Risco da mudança: <classificação> (<motivos>).

  [1] Correção direta
      Sigo com a estratégia que propus. Mais rápido.
  [2] Debate multiagente
      /reversa-debugger-debate em modo <diagnosis|repair> com N agentes por R rodadas + juiz.
      Atenção: demora e custa mais (padrão 3x2 = 6 chamadas + juiz).
      <se detectado: "Detectei <harness> 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-<ID>-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/<contexto>/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.