wangnan0916/runtime-debug-toolkit

Modo de Depuração

Inicie uma sessão apenas quando o usuário atual invocar $debug-mode, disser "modo de depuração" ou solicitar depuração instrumentada. Retome sempre que existir uma sessão de depuração ativa, inclusive após respostas do usuário ou compactação de contexto. A sessão se torna ativa quando o Passo 3 arma o servidor. Ela termina apenas após a limpeza do Passo 8 ou abandono explícito. Se nenhuma condição se aplicar, pare antes da análise, coleta ou instrumentação.

Este workflow se baseia no workflow irmão trace-mode. Ele estende a evidência de localização por meio de correção, verificação e limpeza. Os scripts irmãos exigem Node.js 24 ou superior.

Execute este loop de evidências:

analisar código -> hipotetizar -> rastrear com trace-mode -> provar -> corrigir -> verificar -> limpar

Trabalhe autonomamente através da instrumentação. A primeira interação planejada com o usuário é o ponto de verificação de reprodução. Reprodução e verificação são portões.

Invariante do ponto de verificação: toda tentativa manual de reprodução ou verificação requer um novo ponto de verificação. A disponibilidade de ferramentas sozinha seleciona seu caminho: quando o request_user_input nativo do Codex estiver listado, você DEVE chamá-lo; caso contrário, chame o seletor Pi quando listado; use o modelo de texto simples exato somente após nenhum caminho interativo poder ser executado. A chamada de ferramenta nativa é o ponto de verificação; comentário ou resposta final não podem substituí-la. Um cancelamento nativo deixa o portão pendente, e um resultado anterior autoriza apenas sua tentativa atual.

1. Analisar o Caminho do Código

Inicie o trabalho de reconhecimento do repositório a partir do sintoma relatado. Leia pontos de entrada, manipuladores, transições de estado, logs existentes e alterações recentes relevantes. Mapeie caminhos candidatos do gatilho do usuário até o resultado observado. Escreva um Cartão de Bug:

• Sintoma e comportamento esperado
• Gatilho, rota, comando, entrada ou fixture conhecido
• Caminho de runtime candidato e limites contestados
• Ambiente, frequência, alterações e evidências relevantes
• Critério de aceitação observável

Registre fatos indisponíveis como desconhecido. Resolva desconhecimentos consequentes por meio de leitura de código ou sondas de runtime discriminatórias.

Completo quando: um caminho candidato liga o gatilho ao sintoma, e cada ramo contestado tem um limite de sonda nomeado.

2. Construir a Matriz de Hipóteses

Escreva de duas a cinco hipóteses classificadas antes de adicionar sondas. Ancore a matriz na análise de código e evidências disponíveis. Use este formato:

H1 <causa curta>
Predição: <estado de runtime, caminho ou temporização>
Sonda: <nomes de eventos e locais de código>
CONFIRMADA quando: <condição de registro específica>
REJEITADA quando: <condição de registro específica>

Uma hipótese sem uma predição concreta requer mais leitura de código. Prefira sondas que separem múltiplas hipóteses.

Completo quando: toda hipótese tem condições falseáveis e uma sonda planejada discriminatória.

3. Rastrear Através do Trace Mode

Leia o skill irmão trace-mode. Use suas etapas de planejamento de eventos, inicialização do servidor e instrumentação com o Cartão de Bug. Leia references/probes.md para a extensão de eventos de depuração. Retorne aqui antes de seu ponto de verificação de rastreamento independente.

Este workflow é o chamador. O workflow trace-mode deve devolver sondas ativas e os cinco valores do servidor.

Completo quando: toda hipótese tem uma sonda ativa e todos os cinco valores do servidor são conhecidos.

4. Atravessar o Portão de Reprodução

Leia references/checkpoints.md antes de apresentar o ponto de verificação pré-correção. Execute o protocolo pré-correção através do caminho do ponto de verificação selecionado acima. Em seguida, aguarde e direcione seu resultado através da tabela de estados. Toda nova tentativa retorna por este portão com uma nova chamada interativa.

Completo quando: um resultado válido A, B ou C foi direcionado por fase.

5. Provar a Causa

Após a pré-correção A, leia os registros da sessão atual em LOG_FILE antes de editar o código do produto. Confirme que toda sonda esperada está presente, então inspecione os registros na ordem do arquivo e compare os valores relevantes com cada predição da hipótese. Classifique cada hipótese como CONFIRMADA, REJEITADA ou INCONCLUSIVA. Escreva o relatório de evidências:

H1 <causa curta>
Status: CONFIRMADA
Evidência: <eventos e valores específicos>

H2 <causa curta>
Status: REJEITADA
Evidência: <eventos e valores específicos>

Aceitação: <uma sentença observável>
Próxima ação: <menor correção para a causa confirmada>

Sondas esperadas ausentes bloqueiam a confirmação. Retorne ao Passo 2 quando todo resultado for rejeitado ou inconclusivo.

Completo quando: os registros da execução atual confirmam uma causa explicativa, com um critério de aceitação observável.

6. Fazer a Correção Vinculada à Evidência

Faça a menor alteração que aborde a causa confirmada. Mantenha toda sonda ativa. Altere eventos para runId: "post-fix". Adicione um teste de regressão focado quando o comportamento for automatizável.

Completo quando: cada edição do produto rastreia a causa, e a evidência pós-correção está pronta.

7. Atravessar o Portão de Verificação

Apresente o ponto de verificação pós-correção de references/checkpoints.md através do caminho selecionado. Em seguida, aguarde e direcione seu resultado através da tabela de estados. Toda tentativa de verificação posterior requer outra chamada interativa.

Completo quando: o usuário retorna pós-correção B para o critério de aceitação declarado.

8. Limpar Mecanicamente

Remova todo par marcado LOG_SERVER_PROBE <session_id>. Pesquise pelo ID da sessão, LOG_SERVER_PROBE e ambas as formas de região. Remova ajudantes copiados e toda instrumentação temporária. Exclua LOG_FILE a menos que o usuário solicite evidências retidas. Mantenha o servidor compartilhado em execução a menos que o usuário solicite desligamento. Execute verificações relevantes e inspecione o diff final.

Completo quando: as pesquisas de marcador e sessão retornam zero correspondências no repositório, as verificações passam e apenas as alterações do produto permanecem.

Ramo de Exceção

Leia references/troubleshooting.md apenas quando a coleta, reprodução ou entrega falhar.