Depuração por Introspecção do Agente

O que Depuração por Introspecção do Agente faz?

Use esta skill quando a execução de um agente falhar repetidamente, consumir tokens sem progresso, entrar em loop nas mesmas ferramentas ou se desviar da tarefa pretendida.

Esta é uma skill de fluxo de trabalho, não um runtime oculto. Ela ensina o agente a se depurar sistematicamente antes de escalar para um humano.

Quando Ativar

• Falhas máximas de chamada de ferramenta / limite de loop
• Tentativas repetidas sem progresso
• Crescimento do contexto ou desvio de prompt que começa a degradar a qualidade da saída
• Incompatibilidade de estado do sistema de arquivos ou ambiente entre expectativa e realidade
• Falhas de ferramentas que provavelmente são recuperáveis com diagnóstico e uma ação corretiva menor

Limites de Escopo

Ative esta skill para:

• capturar o estado da falha antes de tentar novamente cegamente
• diagnosticar padrões comuns de falha específicos de agentes
• aplicar ações de recuperação contidas
• produzir um relatório de depuração estruturado e legível por humanos

Não use esta skill como fonte principal para:

• verificação de funcionalidades após alterações de código; use verification-loop
• depuração específica de framework quando uma skill ECC mais restrita já existir
• promessas de runtime que o harness atual não pode aplicar automaticamente

Loop de Quatro Fases

Fase 1: Captura da Falha

Antes de tentar recuperar, registre a falha com precisão.

Capture:

• tipo de erro, mensagem e stack trace, quando disponíveis
• última sequência significativa de chamadas de ferramenta
• o que o agente estava tentando fazer
• pressão atual do contexto: prompts repetidos, logs colados muito grandes, planos duplicados ou notas descontroladas
• suposições atuais do ambiente: cwd, branch, estado relevante do serviço, arquivos esperados

Modelo mínimo de captura:

## Captura da Falha
- Sessão / tarefa:
- Objetivo em andamento:
- Erro:
- Última etapa bem-sucedida:
- Última ferramenta / comando com falha:
- Padrão repetido observado:
- Suposições do ambiente a verificar:

Fase 2: Diagnóstico da Causa Raiz

Corresponda a falha a um padrão conhecido antes de alterar qualquer coisa.

Padrão	Causa Provável	Verificação
Máximo de chamadas de ferramenta / mesmo comando repetido	loop ou caminho de observador sem saída	inspecione as últimas N chamadas de ferramenta em busca de repetição
Overflow de contexto / raciocínio degradado	notas ilimitadas, planos repetidos, logs muito grandes	inspecione o contexto recente em busca de duplicação e volume de baixo sinal
ECONNREFUSED / timeout	serviço indisponível ou porta errada	verifique a integridade do serviço, URL e suposições de porta
429 / cota exaurida	tempestade de repetições ou falta de backoff	conte as chamadas repetidas e inspecione o espaçamento das repetições
arquivo ausente após gravação / diff desatualizado	condição de corrida, cwd errado ou desvio de branch	verifique novamente o caminho, cwd, status do git e existência real do arquivo
testes ainda falhando após "correção"	hipótese errada	isole o teste exato que falha e rededuza o bug

Perguntas de diagnóstico:

• isso é uma falha de lógica, falha de estado, falha de ambiente ou falha de política?
• o agente perdeu o objetivo real e começou a otimizar a subtarefa errada?
• a falha é determinística ou transitória?
• qual é a menor ação reversível que validaria o diagnóstico?

Fase 3: Recuperação Contida

Recupere com a menor ação que mude a superfície de diagnóstico.

Ações de recuperação seguras:

• pare as tentativas repetidas e reafirme a hipótese
• remova contexto de baixo sinal e mantenha apenas o objetivo ativo, bloqueadores e evidências
• verifique novamente o estado real do sistema de arquivos / branch / processo
• restrinja a tarefa a um comando com falha, um arquivo ou um teste
• mude de raciocínio especulativo para observação direta
• escale para um humano quando a falha for de alto risco ou bloqueada externamente

Não reivindique ações de autocorreção não suportadas, como "redefinir estado do agente" ou "atualizar configuração do harness", a menos que você esteja realmente fazendo isso através de ferramentas reais no ambiente atual.

Lista de verificação de recuperação contida:

## Ação de Recuperação
- Diagnóstico escolhido:
- Menor ação tomada:
- Por que isso é seguro:
- Que evidências provariam que a correção funcionou:

Fase 4: Relatório de Introspecção

Termine com um relatório que torne a recuperação legível para o próximo agente ou humano.

## Relatório de Autodepuração do Agente
- Sessão / tarefa:
- Falha:
- Causa raiz:
- Ação de recuperação:
- Resultado: sucesso | parcial | bloqueado
- Risco de consumo de token / tempo:
- Acompanhamento necessário:
- Mudança preventiva para codificar depois:

Heurísticas de Recuperação

Prefira estas intervenções em ordem:

1. Reafirme o objetivo real em uma frase.
2. Verifique o estado do mundo em vez de confiar na memória.
3. Reduza o escopo da falha.
4. Execute uma verificação discriminatória.
5. Só então tente novamente.

Padrão ruim:

• tentar a mesma ação três vezes com palavras ligeiramente diferentes

Padrão bom:

• capturar a falha
• classificar o padrão
• executar uma verificação direta
• alterar o plano somente se a verificação o suportar

Integração com ECC

• Use verification-loop após a recuperação se o código foi alterado.
• Use continuous-learning-v2 quando o padrão de falha valer a pena ser transformado em um instinto ou skill posterior.
• Use council quando o problema não for falha técnica, mas ambiguidade de decisão.
• Use workspace-surface-audit se a falha veio de estado local conflitante ou desvio do repositório.

Padrão de Saída

Quando esta skill estiver ativa, não termine apenas com "Eu consertei".

Sempre forneça:

• o padrão de falha
• a hipótese da causa raiz
• a ação de recuperação
• a evidência de que a situação agora está melhor ou ainda bloqueada