Depuração por Introspecção de Agente

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

Use esta skill quando uma execução de agente estiver falhando repetidamente, consumindo tokens sem progresso, entrando em loop nas mesmas ferramentas ou se desviando 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
• Novas tentativas repetidas sem progresso
• Crescimento de contexto ou deriva 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 ferramenta que são provavelmente recuperáveis com diagnóstico e uma ação corretiva menor

Limites de Escopo

Ative esta skill para:

• capturar o estado de 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 para humanos

Não use esta skill como fonte principal para:

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

Loop em Quatro Fases

Fase 1: Captura de Falha

Antes de tentar se recuperar, registre a falha precisamente.

Capture:

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

Modelo de captura mínimo:

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

Fase 2: Diagnóstico de Causa Raiz

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

Padrão	Causa Provável	Verificar
Chamadas máximas de ferramenta / mesmo comando repetido	loop ou caminho de observador sem saída	inspecionar as últimas N chamadas de ferramenta em busca de repetição
Estouro de contexto / raciocínio degradado	notas sem limite, planos repetidos, logs superdimensionados	inspecionar contexto recente em busca de duplicação e volume de baixo sinal
ECONNREFUSED / timeout	serviço indisponível ou porta errada	verificar saúde do serviço, URL e suposições de porta
429 / exaustão de cota	tempestade de repetições ou backoff ausente	contar chamadas repetidas e inspecionar espaçamento de repetições
arquivo ausente após escrita / diff desatualizado	condição de corrida, cwd errado ou deriva de branch	verificar novamente caminho, cwd, status do git e existência real do arquivo
testes ainda falhando após "correção"	hipótese errada	isolar o teste exato que falha e rederivar 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 altere a superfície de diagnóstico.

Ações de recuperação seguras:

• parar repetições repetidas e reafirmar a hipótese
• cortar contexto de baixo sinal e manter apenas o objetivo ativo, bloqueadores e evidências
• verificar novamente o sistema de arquivos / branch / estado do processo real
• restringir a tarefa a um comando falho, um arquivo ou um teste
• mudar de raciocínio especulativo para observação direta
• escalar para um humano quando a falha for de alto risco ou bloqueada externamente

Não reivindique ações de autocuração não suportadas, como "redefinir estado do agente" ou "atualizar configuração do harness", a menos que você esteja realmente realizando-as por meio 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ência provaria 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 queima de token / tempo:
- Acompanhamento necessário:
- Mudança preventiva a codificar posteriormente:

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 discriminante.
5. Só então tente novamente.

Padrão ruim:

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

Padrão bom:

• capturar falha
• classificar o padrão
• executar uma verificação direta
• alterar o plano somente se a verificaçã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 se tornar 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 deriva de repositório.

Padrão de Saída

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

Sempre forneça:

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