Modo de Depuración
Inicia una sesión solo cuando el usuario actual invoca $debug-mode, dice "modo de depuración" o solicita depuración instrumentada.
Reanuda siempre que exista una sesión de depuración activa, incluso después de respuestas del usuario o compactación de contexto.
La sesión se activa cuando el Paso 3 arma el servidor.
Finaliza solo después de la limpieza del Paso 8 o abandono explícito.
Si no se cumple ninguna de estas condiciones, detente antes del análisis, recolección o instrumentación.
Este flujo de trabajo se basa en el flujo de trabajo hermano trace-mode.
Extiende la evidencia de ubicación mediante corrección, verificación y limpieza.
Los scripts hermanos requieren Node.js 24 o posterior.
Ejecuta este bucle de evidencia:
analizar código -> hipotetizar -> rastrear con trace-mode -> probar -> corregir -> verificar -> limpiar
Trabaja de forma autónoma mediante instrumentación. La primera interacción planificada con el usuario es el punto de control de reproducción. La reproducción y verificación son compuertas.
Invariante del punto de control: cada intento de reproducción o verificación manual requiere un punto de control nuevo.
La disponibilidad de la herramienta selecciona su ruta: cuando el request_user_input nativo de Codex está listado, DEBES llamarlo;
de lo contrario, llama al selector Pi cuando esté listado; usa la plantilla de texto plano exacta solo cuando ninguna ruta interactiva pueda ejecutarse.
La llamada a la herramienta nativa es el punto de control; los comentarios o una respuesta final no pueden reemplazarla.
Una cancelación nativa deja la compuerta pendiente, y un resultado anterior autoriza solo su intento actual.
1. Analizar la Ruta del Código
Comienza el trabajo de base en el repositorio a partir del síntoma reportado. Lee los puntos de entrada, manejadores, transiciones de estado, registros existentes y cambios recientes relevantes. Mapea las rutas candidatas desde el desencadenante del usuario hasta el resultado observado. Escribe una Tarjeta de Error:
- Síntoma y comportamiento esperado
- Desencadenante, ruta, comando, entrada o fixture conocido
- Ruta de ejecución candidata y límites en disputa
- Entorno, frecuencia, cambios y evidencia relevantes
- Criterio de aceptación observable
Registra los hechos no disponibles como desconocido.
Resuelve incógnitas consecuentes mediante lectura de código o sondas de tiempo de ejecución discriminatorias.
Completado cuando: una ruta candidata vincula el desencadenante con el síntoma, y cada rama en disputa tiene un límite de sonda nombrado.
2. Construir la Matriz de Hipótesis
Escribe de dos a cinco hipótesis clasificadas antes de agregar sondas. Ancla la matriz en el análisis de código y la evidencia disponible. Usa esta forma:
H1 <causa breve>
Predicción: <estado, ruta o temporización en tiempo de ejecución>
Sonda: <nombres de eventos y ubicaciones de código>
CONFIRMADA cuando: <condición de registro específica>
RECHAZADA cuando: <condición de registro específica>
Una hipótesis sin una predicción concreta requiere más lectura de código. Prefiere sondas que separen múltiples hipótesis.
Completado cuando: cada hipótesis tiene condiciones falsables y una sonda planificada que las distinga.
3. Rastrear a través del Modo de Traza
Lee el skill hermano trace-mode.
Usa sus pasos de planificación de eventos, inicio del servidor e instrumentación con la Tarjeta de Error.
Lee references/probes.md para la extensión de eventos de depuración.
Regresa aquí antes de su punto de control de traza independiente.
Este flujo de trabajo es el llamador. El flujo de trabajo trace-mode debe devolver las sondas activas y los cinco valores del servidor.
Completado cuando: cada hipótesis tiene una sonda activa y se conocen los cinco valores del servidor.
4. Cruzar la Compuerta de Reproducción
Lee references/checkpoints.md antes de presentar el punto de control previo a la corrección.
Ejecuta el protocolo previo a la corrección a través de la ruta de punto de control seleccionada anteriormente.
Luego espera y enruta su resultado a través de la tabla de estados.
Cada reintento regresa por esta compuerta con una nueva llamada interactiva.
Completado cuando: un resultado válido A, B o C ha sido enrutado por fase.
5. Probar la Causa
Después de la A previa a la corrección, lee los registros de sesión actuales en LOG_FILE antes de editar el código del producto.
Confirma que cada sonda esperada esté presente, luego inspecciona los registros en orden de archivo y compara los valores relevantes con cada predicción de hipótesis.
Clasifica cada hipótesis como CONFIRMADA, RECHAZADA o NO CONCLUYENTE.
Escribe el informe de evidencia:
H1 <causa breve>
Estado: CONFIRMADA
Evidencia: <eventos y valores específicos>
H2 <causa breve>
Estado: RECHAZADA
Evidencia: <eventos y valores específicos>
Aceptación: <una oración observable>
Próxima acción: <corrección más pequeña para la causa confirmada>
La falta de sondas esperadas bloquea la confirmación. Regresa al Paso 2 cuando cada resultado sea rechazado o no concluyente.
Completado cuando: los registros de la ejecución actual confirman una causa explicativa, con un criterio de aceptación observable.
6. Realizar la Corrección Basada en Evidencia
Haz el cambio más pequeño que aborde la causa confirmada.
Mantén cada sonda activa.
Cambia los eventos a runId: "post-fix".
Agrega una prueba de regresión enfocada cuando el comportamiento sea automatizable.
Completado cuando: cada edición del producto se rastrea hasta la causa, y la evidencia posterior a la corrección está lista.
7. Cruzar la Compuerta de Verificación
Presenta el punto de control posterior a la corrección desde references/checkpoints.md a través de la ruta seleccionada.
Luego espera y enruta su resultado a través de la tabla de estados.
Cada intento de verificación posterior requiere otra llamada interactiva.
Completado cuando: el usuario devuelve B posterior a la corrección para el criterio de aceptación establecido.
8. Limpiar de Forma Mecánica
Elimina cada par de regiones marcadas con LOG_SERVER_PROBE <session_id>.
Busca el ID de sesión, LOG_SERVER_PROBE y ambas formas de región.
Elimina los ayudantes copiados y toda la instrumentación temporal.
Borra LOG_FILE a menos que el usuario solicite conservar la evidencia.
Mantén el servidor compartido en ejecución a menos que el usuario solicite apagarlo.
Ejecuta las comprobaciones relevantes e inspecciona el diff final.
Completado cuando: las búsquedas de marcador y sesión devuelvan cero coincidencias en el repositorio, las comprobaciones pasen y solo queden cambios en el producto.
Rama de Excepción
Lee references/troubleshooting.md solo cuando la recolección, reproducción o entrega fallen.