Depuración de Introspección de Agente

¿Qué hace Depuración de Introspección de Agente?

Usa esta habilidad cuando una ejecución de agente esté fallando repetidamente, consumiendo tokens sin progreso, en bucle en las mismas herramientas o desviándose de la tarea prevista.

Esta es una habilidad de flujo de trabajo, no un runtime oculto. Enseña al agente a depurarse sistemáticamente antes de escalar a un humano.

Cuándo activarla

• Límite máximo de llamadas a herramientas / fallos de bucle
• Reintentos repetidos sin avance
• Crecimiento del contexto o deriva del prompt que comienza a degradar la calidad de la salida
• Desajuste entre el estado esperado y real del sistema de archivos o entorno
• Fallos de herramientas que probablemente se puedan recuperar con diagnóstico y una acción correctiva pequeña

Límites del alcance

Activa esta habilidad para:

• capturar el estado de fallo antes de reintentar a ciegas
• diagnosticar patrones de fallo comunes específicos de agentes
• aplicar acciones de recuperación controladas
• producir un informe de depuración estructurado y legible por humanos

No uses esta habilidad como fuente principal para:

• verificación de funcionalidad después de cambios de código; usa verification-loop
• depuración específica de un framework cuando ya existe una habilidad ECC más específica
• promesas de runtime que el harness actual no pueda aplicar automáticamente

Bucle de Cuatro Fases

Fase 1: Captura de Fallo

Antes de intentar recuperarte, registra el fallo con precisión.

Captura:

• tipo de error, mensaje y traza de pila cuando esté disponible
• última secuencia significativa de llamadas a herramientas
• qué intentaba hacer el agente
• presión actual del contexto: prompts repetidos, registros pegados sobredimensionados, planes duplicados o notas descontroladas
• suposiciones actuales del entorno: cwd, rama, estado relevante del servicio, archivos esperados

Plantilla mínima de captura:

## Captura de Fallo
- Sesión / tarea:
- Objetivo en curso:
- Error:
- Último paso exitoso:
- Última herramienta / comando fallido:
- Patrón repetido observado:
- Suposiciones del entorno a verificar:

Fase 2: Diagnóstico de Causa Raíz

Relaciona el fallo con un patrón conocido antes de cambiar nada.

Patrón	Causa Probable	Verificar
Máximo de llamadas a herramientas / mismo comando repetido	bucle o ruta observadora sin salida	inspeccionar las últimas N llamadas a herramientas en busca de repetición
Desbordamiento de contexto / razonamiento degradado	notas sin límite, planes repetidos, registros sobredimensionados	inspeccionar el contexto reciente en busca de duplicación y gran volumen de baja señal
ECONNREFUSED / tiempo de espera agotado	servicio no disponible o puerto incorrecto	verificar estado del servicio, URL y suposiciones de puerto
429 / cuota agotada	tormenta de reintentos o falta de retroceso	contar llamadas repetidas e inspeccionar el espaciado de reintentos
archivo faltante después de escritura / diff obsoleto	condición de carrera, cwd incorrecto o deriva de rama	re-verificar ruta, cwd, estado de git y existencia real del archivo
pruebas siguen fallando después de "arreglo"	hipótesis incorrecta	aislar la prueba exacta que falla y derivar de nuevo el error

Preguntas de diagnóstico:

• ¿es un fallo lógico, de estado, de entorno o de política?
• ¿perdió el agente el objetivo real y comenzó a optimizar la subtarea equivocada?
• ¿es el fallo determinista o transitorio?
• ¿cuál es la acción reversible más pequeña que validaría el diagnóstico?

Fase 3: Recuperación Controlada

Recupérate con la acción más pequeña que cambie la superficie de diagnóstico.

Acciones de recuperación seguras:

• detener reintentos repetidos y reafirmar la hipótesis
• recortar contexto de baja señal y mantener solo el objetivo activo, los bloqueos y la evidencia
• re-verificar el estado real del sistema de archivos / rama / proceso
• reducir la tarea a un comando fallido, un archivo o una prueba
• cambiar de razonamiento especulativo a observación directa
• escalar a un humano cuando el fallo sea de alto riesgo o esté bloqueado externamente

No afirmes acciones de auto-recuperación no compatibles como "restablecer estado del agente" o "actualizar configuración del harness" a menos que realmente las estés realizando a través de herramientas reales en el entorno actual.

Lista de verificación de recuperación controlada:

## Acción de Recuperación
- Diagnóstico elegido:
- Acción más pequeña tomada:
- Por qué es segura:
- Qué evidencia probaría que la corrección funcionó:

Fase 4: Informe de Introspección

Termina con un informe que haga legible la recuperación para el próximo agente o humano.

## Informe de Auto-Depuración del Agente
- Sesión / tarea:
- Fallo:
- Causa raíz:
- Acción de recuperación:
- Resultado: éxito | parcial | bloqueado
- Riesgo de consumo de tokens / tiempo:
- Seguimiento necesario:
- Cambio preventivo a codificar después:

Heurísticas de Recuperación

Prefiere estas intervenciones en orden:

1. Reafirmar el objetivo real en una frase.
2. Verificar el estado del mundo en lugar de confiar en la memoria.
3. Reducir el alcance del fallo.
4. Ejecutar una verificación discriminante.
5. Solo entonces reintentar.

Patrón malo:

• reintentar la misma acción tres veces con redacción ligeramente diferente

Patrón bueno:

• capturar fallo
• clasificar el patrón
• ejecutar una verificación directa
• cambiar el plan solo si la verificación lo respalda

Integración con ECC

• Usa verification-loop después de la recuperación si se modificó código.
• Usa continuous-learning-v2 cuando el patrón de fallo merezca convertirse en un instinto o habilidad posterior.
• Usa council cuando el problema no sea un fallo técnico sino ambigüedad en la decisión.
• Usa workspace-surface-audit si el fallo provino de un estado local conflictivo o deriva del repositorio.

Estándar de Salida

Cuando esta habilidad esté activa, no termines solo con "lo arreglé".

Siempre proporciona:

• el patrón de fallo
• la hipótesis de causa raíz
• la acción de recuperación
• la evidencia de que la situación ahora está mejor o aún bloqueada