wangnan0916/debug-mode-skill

Modo Depuración

Usa esta habilidad solo después de que el usuario invoque explícitamente debug-mode, $debug-mode, debug mode o depuración instrumentada.

Si el usuario no optó explícitamente por ello, depura con normalidad. Menciona esta habilidad solo cuando la instrumentación temporal en tiempo de ejecución ayudaría de manera significativa.

Bucle Principal

Ejecuta un bucle de depuración basado en hipótesis:

1. Lee el código relevante, los detalles de reproducción y los registros existentes.
2. Enumera de 2 a 5 hipótesis clasificadas con identificadores como H1, H2 y H3. Cada hipótesis debe predecir lo que mostrará una sonda de tiempo de ejecución.
3. Inicia o reutiliza el colector de bucle cerrado (Contrato del Colector).
4. Añade de 3 a 8 sondas dirigidas que distingan las hipótesis. Usa eventos estructurados enviados a DEBUG_URL + "/log", nunca a stdout/stderr. Sigue la Forma del Evento, los Marcadores de Región y las Ayudas a continuación.
5. Detente en el punto de control manual. Envía una Plantilla de Punto de Control. No analices, corrijas ni elimines sondas hasta que el usuario responda con A, B o C.
6. Después de A, inspecciona el LOG_FILE impreso, clasifica cada hipótesis como CONFIRMADA, RECHAZADA o NO CONCLUYENTE, y realiza la corrección más pequeña solo cuando los registros expliquen la causa raíz. Sigue el Resumen de Evidencia a continuación.
7. Mantén las sondas activas durante una ejecución posterior a la corrección etiquetada con runId: "post-fix".
8. Después de que el usuario responda B al punto de control posterior a la corrección, elimina toda la instrumentación y ejecuta las comprobaciones relevantes. Sigue la Lista de Verificación de Limpieza a continuación.

Reglas Estrictas

• No omitas nunca el punto de control de reproducción manual después de añadir sondas.
• No corrijas basándote en suposiciones mientras esta habilidad esté activa.
• No elimines sondas antes de que el usuario confirme la verificación posterior a la corrección.
• No confirmes registros de depuración ni instrumentación temporal.
• No registres secretos, tokens, cookies, cabeceras de autorización, claves de API, cuerpos de solicitud sin procesar, respuestas sin procesar que puedan contener datos privados o datos personales innecesarios.

Contrato del Colector

El colector incluido es intencionalmente pequeño:

• GET /health comprueba si un colector existente es reutilizable.
• POST /log acepta un objeto JSON y añade una línea NDJSON de forma asíncrona. Devuelve 200 después de la validación; la línea se escribe en segundo plano.
• Las diferentes sesiones escriben en archivos separados con colas independientes, por lo que las escrituras pueden proceder en paralelo entre sesiones.
• Los registros se almacenan por defecto en el directorio temporal del SO, fuera del espacio de trabajo.
• --ensure imprime DEBUG_URL, SESSION_ID, LOG_DIR, LOG_FILE y HEALTH_URL.
• El colector crea LOG_FILE en el primer evento. No uses touch, pre-crees, trunques ni limpies después de una reproducción.
• El colector es solo de bucle cerrado. No lo vincules a 0.0.0.0 ni a ninguna interfaz pública.

Inícialo o reutilízalo con:

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

En entornos limitados gestionados que bloquean los oyentes de puertos locales, solicita la aprobación normal del agente en el primer intento. Limita el motivo a iniciar o reutilizar este colector de depuración de bucle cerrado.

Plantillas de Punto de Control

Después de añadir sondas, detente y envía esta forma con los detalles reales de la sesión:

He añadido sondas de modo depuración y el colector está escribiendo:

- Sesión: <session_id>
- Archivo de registro: <LOG_FILE>
- Punto final de depuración: <DEBUG_URL>/log

Por favor, reproduce el error manualmente y luego responde:

A - Reproducido
B - Corregido
C - Otro; describe lo que ocurrió

Para la verificación posterior a la corrección, cambia solo la oración inicial:

He mantenido las sondas de modo depuración activas para la verificación posterior a la corrección y el colector está escribiendo:

- Sesión: <session_id>
- Archivo de registro: <LOG_FILE>
- Punto final de depuración: <DEBUG_URL>/log

Por favor, verifica el error original manualmente y luego responde:

A - Reproducido
B - Corregido
C - Otro; describe lo que ocurrió

Interpreta las respuestas del punto de control como una pequeña máquina de estados:

• A antes de una corrección: lee el registro NDJSON, clasifica la evidencia de la hipótesis, luego corrige solo una causa confirmada o añade sondas más específicas.
• A después de una corrección: el error aún se reproduce. Lee el registro posterior a la corrección y continúa con hipótesis o sondas más específicas.
• B antes de una corrección: no es un estado terminal. Trátalo como evidencia de que el error no se reprodujo bajo instrumentación y pide aclaración o una reproducción más específica.
• B después de una corrección: elimina sondas y ejecuta comprobaciones finales.
• C en cualquier momento: trata el texto del usuario como evidencia. Ajusta la reproducción, las hipótesis o las sondas.

Forma del Evento

Utiliza eventos estructurados y de bajo volumen. Un evento típico tiene este aspecto:

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

Usa runId: "pre-fix" antes de la corrección y runId: "post-fix" para la verificación. Para rutas de alta frecuencia, registra solo en cambios de estado o muestrea de forma agresiva.

Marcadores de Región

Envuelve toda la instrumentación temporal para que la limpieza sea 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 comentario comunes:

// #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 y contextos de bloque estilo C
-- #region DEBUG_MODE_PROBE <session_id> ...    SQL, Lua

Ayudas

Para JavaScript de navegador o frontend, usa assets/browser-log-helper.js como la plantilla auxiliar canónica. Cópiala en el módulo o script instrumentado, reemplaza <session_id> y <DEBUG_URL>, y mantén el nombre de función debugModeLog.

Para JavaScript de Node.js o lado servidor, usa assets/node-log-helper.js como la plantilla auxiliar canónica. Cópiala en el módulo o script instrumentado, reemplaza <session_id> y <DEBUG_URL>, y mantén el nombre de función debugModeLog.

Para Python sin dependencias de terceros:

# #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>

Resumen de Evidencia

Después de una respuesta A, resume la evidencia antes de editar el código:

H1 El estado de configuración se pierde antes de la llamada a la API
Estado: CONFIRMADA
Evidencia: settings.beforePersist registró enabled=false mientras que el evento de interfaz de usuario registró enabled=true.

H2 La API rechaza el valor
Estado: RECHAZADA
Evidencia: no se realizó ninguna llamada a la API en esta reproducción.

Próxima acción: corregir la transferencia de estado local entre onToggle y saveSettings.

Si cada hipótesis está RECHAZADA o NO CONCLUYENTE, genera nuevas hipótesis a partir de un subsistema diferente y añade sondas más específicas. No apliques parches basados en intuiciones.

Solución de Problemas

• Registro vacío: confirma que la aplicación ejecutó la ruta instrumentada, el identificador de sesión coincide y el punto final incluye /log.
• Solicitud bloqueada en el navegador: verifica contenido mixto, CSP connect-src, aislamiento de extensiones o contexto de script de contenido.
• Problema de CORS/preflight: el colector maneja OPTIONS; si aún falla, prueba navigator.sendBeacon, un proxy de servidor de desarrollo del mismo origen o instrumentación del lado del servidor.
• Host rechazado: usa 127.0.0.1, localhost o ::1; nunca vincules a LAN o interfaces públicas.
• El entorno limitado bloquea el oyente: reintenta una vez con la aprobación requerida para este colector de bucle cerrado. Si la aprobación se deniega, explica que la recopilación local está bloqueada y recurre solo cuando exista una ruta de sonda basada en archivos segura.
• Demasiados registros: reemplaza sondas ruidosas con sondas de cambio de estado más específicas.
• No se puede reproducir: pide pasos exactos, entorno, datos de entrada o una grabación de pantalla; no inventes una corrección.

Lista de Verificación de Limpieza

Antes de declarar la tarea como completada:

• Vuelve a ejecutar la reproducción original o la comprobación automatizada más cercana disponible.
• Elimina cada región emparejada marcada DEBUG_MODE_PROBE <session_id>.
• Busca el identificador de sesión, DEBUG_MODE_PROBE, #region DEBUG_MODE_PROBE y #endregion DEBUG_MODE_PROBE.
• Elimina el registro NDJSON de la sesión en el LOG_FILE impreso, o confirma que debe conservarse como evidencia local.
• Conserva solo la corrección del producto y cualquier prueba de regresión útil.