Modo de Depuração

O que Modo de Depuração faz?

Use este skill apenas após o usuário invocar explicitamente debug-mode, $debug-mode, debug mode, ou depuração instrumentada.

Se o usuário não optou explicitamente, depure normalmente. Mencione este skill apenas quando a instrumentação temporária em tempo de execução ajudar materialmente.

Loop Principal

Execute um loop de depuração orientado por hipóteses:

1. Leia o código relevante, detalhes de reprodução e logs existentes.
2. Liste 2 a 5 hipóteses ranqueadas com IDs como H1, H2 e H3. Cada hipótese deve prever o que uma sonda de tempo de execução mostrará.
3. Inicie ou reutilize o coletor loopback (Contrato do Coletor).
4. Adicione 3 a 8 sondas direcionadas que distinguem as hipóteses. Use eventos estruturados enviados para DEBUG_URL + "/log", nunca stdout/stderr. Siga a Estrutura de Evento, Marcadores de Região e Auxiliares abaixo.
5. Pare no checkpoint manual. Envie um Modelo de Checkpoint. Não analise, corrija ou remova sondas até que o usuário responda com A, B ou C.
6. Após A, inspecione o LOG_FILE impresso, classifique cada hipótese como CONFIRMADA, REJEITADA ou INCONCLUSIVA, e faça a menor correção apenas quando os logs explicarem a causa raiz. Siga o Resumo de Evidências abaixo.
7. Mantenha as sondas ativas para uma execução pós-correção marcada com runId: "post-fix".
8. Após o usuário responder B ao checkpoint pós-correção, remova toda instrumentação e execute verificações relevantes. Siga a Lista de Verificação de Limpeza abaixo.

Regras Rígidas

• Nunca pule o checkpoint manual de reprodução após adicionar sondas.
• Nunca corrija por adivinhação enquanto este skill estiver ativo.
• Nunca remova sondas antes de o usuário confirmar a verificação pós-correção.
• Nunca faça commit de logs de depuração ou instrumentação temporária.
• Nunca registre segredos, tokens, cookies, cabeçalhos de autorização, chaves de API, corpos de requisição brutos, respostas brutas que possam conter dados privados ou dados pessoais desnecessários.

Contrato do Coletor

O coletor incluído é intencionalmente pequeno:

• GET /health verifica se um coletor existente é reutilizável.
• POST /log aceita um objeto JSON e anexa uma linha NDJSON assincronamente. Retorna 200 após validação; a linha é escrita em segundo plano.
• Sessões diferentes escrevem em arquivos separados com filas independentes, para que as escritas possam ocorrer em paralelo entre sessões.
• Os logs ficam no diretório temporário do sistema operacional por padrão, fora do espaço de trabalho.
• --ensure imprime DEBUG_URL, SESSION_ID, LOG_DIR, LOG_FILE e HEALTH_URL.
• O coletor cria LOG_FILE no primeiro evento. Não use touch, pré-crie, trunque ou limpe-o após uma reprodução.
• O coletor é apenas loopback. Não o vincule a 0.0.0.0 ou a qualquer interface pública.

Inicie ou reutilize com:

node <skill-dir>/scripts/log-server.mjs --ensure --session <session_id> --host 127.0.0.1 --port 0

Em sandboxes gerenciados que bloqueiam listeners de porta local, solicite a aprovação normal do agente na primeira tentativa. Escopo o motivo para iniciar ou reutilizar este coletor de depuração apenas loopback.

Modelos de Checkpoint

Após adicionar sondas, pare e envie este formato com detalhes reais da sessão:

Adicionei sondas de modo de depuração e o coletor está escrevendo:

- Sessão: <session_id>
- Arquivo de log: <LOG_FILE>
- Endpoint de depuração: <DEBUG_URL>/log

Por favor, reproduza o bug manualmente e responda:

A - Reproduzido
B - Corrigido
C - Outro; descreva o que aconteceu

Para verificação pós-correção, altere apenas a frase inicial:

Mantive as sondas de modo de depuração ativas para verificação pós-correção e o coletor está escrevendo:

- Sessão: <session_id>
- Arquivo de log: <LOG_FILE>
- Endpoint de depuração: <DEBUG_URL>/log

Por favor, verifique o bug original manualmente e responda:

A - Reproduzido
B - Corrigido
C - Outro; descreva o que aconteceu

Interprete as respostas do checkpoint como uma pequena máquina de estados:

• A antes de uma correção: leia o log NDJSON, classifique as evidências das hipóteses e, em seguida, corrija apenas uma causa confirmada ou adicione sondas mais específicas.
• A após uma correção: o bug ainda foi reproduzido. Leia o log pós-correção e continue com hipóteses ou sondas mais específicas.
• B antes de uma correção: não é um estado terminal. Trate como evidência de que o bug não foi reproduzido sob instrumentação e peça esclarecimentos ou uma reprodução mais específica.
• B após uma correção: remova as sondas e execute verificações finais.
• C a qualquer momento: trate o texto do usuário como evidência. Ajuste a reprodução, hipóteses ou sondas.

Estrutura de Evento

Use eventos estruturados e de baixo volume. Um evento típico se parece com:

{
  "session": "<session_id>",
  "runId": "pre-fix",
  "probe": "settings.beforePersist",
  "hypothesis": "H1",
  "file": "src/settings/save.ts",
  "fn": "saveSettings",
  "vars": {
    "enabled": true,
    "userId": "redacted"
  }
}

Use runId: "pre-fix" antes da correção e runId: "post-fix" para verificação. Para caminhos de alta frequência, registre apenas em mudanças de estado ou realize amostragem agressiva.

Marcadores de Região

Envolva toda instrumentação temporária para que a limpeza seja mecânica:

// #region DEBUG_MODE_PROBE <session_id> settings-before-persist
debugModeLog({
  probe: "settings.beforePersist",
  hypothesis: "H1",
  file: "src/settings/save.ts",
  fn: "saveSettings",
  vars: { enabled, userId: "redacted" },
});
// #endregion DEBUG_MODE_PROBE <session_id>

Formas de comentário comuns:

// #region DEBUG_MODE_PROBE <session_id> ...    JavaScript, TypeScript, Java, C#, Go, Rust, C, C++
# #region DEBUG_MODE_PROBE <session_id> ...     Python, Ruby, Shell, YAML
<!-- #region DEBUG_MODE_PROBE <session_id> -->  HTML, Vue, Svelte
/* #region DEBUG_MODE_PROBE <session_id> */     CSS e contextos de bloco estilo C
-- #region DEBUG_MODE_PROBE <session_id> ...    SQL, Lua

Auxiliares

Para JavaScript de navegador ou frontend, use assets/browser-log-helper.js como o modelo auxiliar canônico. Copie-o para o módulo ou script instrumentado, substitua <session_id> e <DEBUG_URL> e mantenha o nome da função debugModeLog.

Para Node.js ou JavaScript do lado do servidor, use assets/node-log-helper.js como o modelo auxiliar canônico. Copie-o para o módulo ou script instrumentado, substitua <session_id> e <DEBUG_URL> e mantenha o nome da função debugModeLog.

Para Python sem dependências de terceiros:

# #region DEBUG_MODE_PROBE <session_id> debug-log-helper
import json
import urllib.request

DEBUG_MODE_URL = "<DEBUG_URL>/log"

def debug_mode_log(event):
    try:
        payload = {"session": "<session_id>", **event}
        data = json.dumps(payload).encode("utf-8")
        req = urllib.request.Request(
            DEBUG_MODE_URL,
            data=data,
            headers={"content-type": "application/json"},
            method="POST",
        )
        urllib.request.urlopen(req, timeout=0.5).close()
    except Exception:
        pass
# #endregion DEBUG_MODE_PROBE <session_id>

Resumo de Evidências

Após uma resposta A, resuma as evidências antes de editar o código:

H1 O estado das configurações é perdido antes da chamada à API
Status: CONFIRMADA
Evidência: settings.beforePersist registrou enabled=false enquanto o evento de UI registrou enabled=true.

H2 A API rejeita o valor
Status: REJEITADA
Evidência: nenhuma chamada à API ocorreu nesta reprodução.

Próxima ação: corrigir a transferência de estado local entre onToggle e saveSettings.

Se toda hipótese for REJEITADA ou INCONCLUSIVA, gere novas hipóteses a partir de um subsistema diferente e adicione sondas mais específicas. Não faça correções baseadas em suposições.

Solução de Problemas

• Log vazio: confirme que o aplicativo executou o caminho instrumentado, o id da sessão corresponde e o endpoint inclui /log.
• Requisição bloqueada no navegador: verifique mixed content, CSP connect-src, isolamento de extensão ou contexto de content script.
• Problema de CORS/preflight: o coletor lida com OPTIONS; se ainda falhar, tente navigator.sendBeacon, um proxy de servidor de desenvolvimento mesma origem ou instrumentação do lado do servidor.
• Host rejeitado: use 127.0.0.1, localhost ou ::1; nunca vincule a LAN ou interfaces públicas.
• Sandbox bloqueia listener: tente novamente uma vez com a aprovação necessária para este coletor loopback. Se a aprovação for negada, explique que a coleta local está bloqueada e recorra apenas quando existir um caminho seguro de sonda baseado em arquivo.
• Muitos logs: substitua sondas ruidosas por sondas mais específicas de mudança de estado.
• Não é possível reproduzir: peça etapas exatas, ambiente, dados de entrada ou uma gravação de tela; não invente uma correção.

Lista de Verificação de Limpeza

Antes de declarar a tarefa concluída:

• Execute novamente a reprodução original ou a verificação automatizada mais próxima disponível.
• Remova cada par de região marcado com DEBUG_MODE_PROBE <session_id>.
• Pesquise pelo id da sessão, DEBUG_MODE_PROBE, #region DEBUG_MODE_PROBE e #endregion DEBUG_MODE_PROBE.
• Remova o log NDJSON da sessão no LOG_FILE impresso ou confirme que deve ser mantido como evidência local.
• Mantenha apenas a correção do produto e qualquer teste de regressão útil.