Depuración por Introspección del Agente

¿Qué hace Depuración por Introspección del Agente?

Usa esta habilidad cuando una ejecución del agente falle repetidamente, consuma tokens sin progreso, se enganche en las mismas herramientas o se desvíe de la tarea prevista.

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

Cuándo Activar

• Fallos por límite máximo de llamadas a herramientas / bucles
• Reintentos repetidos sin ningún progreso
• Crecimiento del contexto o deriva del prompt que empieza a degradar la calidad de la salida
• Desajuste entre el estado esperado y el real del sistema de archivos o del 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 del fallo antes de reintentar ciegamente
• diagnosticar patrones de fallo comunes específicos de agentes
• aplicar acciones de recuperación controladas
• producir un informe de depuración legible por humanos

No uses esta habilidad como fuente principal para:

• verificación de funcionalidades tras cambios de código; usa verification-loop
• depuración específica de un framework cuando ya exista una habilidad ECC más específica
• promesas de tiempo de ejecución que el harness actual no pueda garantizar automáticamente

Bucle de Cuatro Fases

Fase 1: Captura del 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 de llamadas a herramientas significativa
• qué intentaba hacer el agente
• presión actual del contexto: avisos repetidos, registros pegados de gran tamaño, planes duplicados o notas descontroladas
• suposiciones actuales del entorno: directorio de trabajo, rama, estado relevante del servicio, archivos esperados

Plantilla mínima de captura:

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

Clasifica el fallo según un patrón conocido antes de cambiar nada.

Patrón	Causa Probable	Verificación
Máximo de llamadas a herramientas / mismo comando repetido	Bucle o trayectoria de observación sin salida	Inspecciona las últimas N llamadas a herramientas en busca de repetición
Desbordamiento de contexto / razonamiento degradado	Notas sin límite, planes repetidos, registros de gran tamaño	Inspecciona el contexto reciente en busca de duplicación y contenido masivo de baja señal
ECONNREFUSED / tiempo de espera	Servicio no disponible o puerto incorrecto	Verifica el estado del servicio, la URL y las suposiciones del puerto
429 / cuota agotada	Tormenta de reintentos o falta de retroceso	Cuenta las llamadas repetidas e inspecciona el espaciado entre reintentos
Archivo faltante tras escritura / diff obsoleto	Condición de carrera, directorio de trabajo incorrecto o deriva de rama	Revisa la ruta, el directorio de trabajo, el estado de git y la existencia real del archivo
Pruebas aún fallando tras la "solución"	Hipótesis incorrecta	Aísla la prueba que falla exactamente y rededuce 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 incorrecta?
• ¿El fallo es 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 del diagnóstico.

Acciones de recuperación seguras:

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

No afirmes acciones de autocuración no compatibles como "restablecer el estado del agente" o "actualizar la 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 realizada:
- Por qué es segura:
- Qué evidencia demostraría que la solució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 Autodepuración del Agente
- Sesión / tarea:
- Fallo:
- Causa raíz:
- Acción de recuperación:
- Resultado: éxito | parcial | bloqueado
- Riesgo de quema de tokens / tiempo:
- Seguimiento necesario:
- Cambio preventivo para codificar después:

Heurísticas de Recuperación

Prefiere estas intervenciones en orden:

1. Reformular 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 una redacción ligeramente diferente

Patrón bueno:

• capturar el 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 cambió 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é".

Proporciona siempre:

• 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 es mejor o sigue bloqueada