AgentDock

Rompe el Ciclo - Análisis Profundo de Errores

Cuando la depuración esté completa, utiliza esto para un análisis profundo que rompa el ciclo de "arreglar error -> olvidar -> repetir".

---

Marco de Análisis

Analiza el error que acabas de corregir desde estas 5 dimensiones:

1. Categoría de la Causa Raíz

¿A qué categoría pertenece este error?

Categoría	Características	Ejemplo
A. Especificación Faltante	Sin documentación sobre cómo hacerlo	Nueva función sin lista de verificación
B. Contrato entre Capas	Interfaz entre capas poco clara	La API devuelve un formato diferente al esperado
C. Fallo en Propagación de Cambios	Cambió un lugar, omitió otros	Cambió la firma de una función, omitió los sitios de llamada
D. Brecha en Cobertura de Pruebas	La prueba unitaria pasa, la integración falla	Funciona solo, falla cuando se combina
E. Suposición Implícita	El código se basa en una suposición no documentada	Segundos vs milisegundos en marcas de tiempo

2. Por qué Fallaron las Correcciones (si aplica)

Si intentaste varias correcciones antes de tener éxito, analiza cada fallo:

• Corrección Superficial: Se arregló el síntoma, no la causa raíz
• Alcance Incompleto: Se encontró la causa raíz, no se cubrieron todos los casos
• Limitación de Herramienta: grep no lo encontró, la verificación de tipos no era estricta
• Modelo Mental: Siguió buscando en la misma capa, no pensó entre capas

3. Mecanismos de Prevención

¿Qué mecanismos evitarían que esto vuelva a ocurrir?

Tipo	Descripción	Ejemplo
Documentación	Escríbelo para que la gente lo sepa	Actualizar la guía de pensamiento
Arquitectura	Haz que el error sea estructuralmente imposible	Envoltorios con seguridad de tipos
Tiempo de Compilación	Verificación de tipos estricta, sin escapes	El cambio de firma provoca un error de compilación
Tiempo de Ejecución	Monitoreo, alertas, escaneos	Detectar entidades huérfanas
Cobertura de Pruebas	Pruebas E2E, pruebas de integración	Verificar el flujo completo
Revisión de Código	Lista de verificación, plantilla PR	"¿Verificaste X?"

4. Expansión Sistemática

¿Qué problemas más amplios revela este error?

• Problemas Similares: ¿Dónde más podría existir este problema?
• Defecto de Diseño: ¿Hay un problema de arquitectura fundamental?
• Defecto de Proceso: ¿Hay una mejora en el proceso de desarrollo?
• Brecha de Conocimiento: ¿Al equipo le falta algún entendimiento?

5. Captura de Conocimiento

Consolida las perspectivas en el sistema:

• Actualizar guías de pensamiento en .trellis/spec/guides/
• Actualizar documentos relevantes en .trellis/spec/
• Crear registro de incidencia (si aplica)
• Crear ticket de funcionalidad para la corrección raíz
• Actualizar pautas de verificación si es necesario

---

Formato de Salida

Por favor, genera el análisis en este formato:

## Análisis de Error: [Descripción Breve]

### 1. Categoría de la Causa Raíz
- **Categoría**: [A/B/C/D/E] - [Nombre de la Categoría]
- **Causa Específica**: [Descripción detallada]

### 2. Por qué Fallaron las Correcciones (si aplica)
1. [Primer intento]: [Por qué falló]
2. [Segundo intento]: [Por qué falló]
...

### 3. Mecanismos de Prevención
| Prioridad | Mecanismo | Acción Específica | Estado |
|-----------|-----------|-------------------|--------|
| P0 | ... | ... | TODO/HECHO |

### 4. Expansión Sistemática
- **Problemas Similares**: [Lista de lugares con problemas similares]
- **Mejora de Diseño**: [Sugerencias a nivel de arquitectura]
- **Mejora de Proceso**: [Sugerencias al proceso de desarrollo]

### 5. Captura de Conocimiento
- [ ] [Documentos a actualizar / tickets a crear]

---

Filosofía Central

El valor de la depuración no está en arreglar el error, sino en hacer que esta clase de errores nunca vuelva a ocurrir.

Tres niveles de perspectiva:

1. Táctico: Cómo arreglar ESTE error
2. Estratégico: Cómo prevenir ESTA CLASE de errores
3. Filosófico: Cómo expandir los patrones de pensamiento

30 minutos de análisis ahorran 30 horas de depuración futura.

Marco de Razonamiento: Razonamiento Bayesiano

Cuando múltiples causas raíz son plausibles y la evidencia está incompleta, actualiza tus creencias proporcionalmente a la nueva evidencia en lugar de aferrarte a las suposiciones iniciales.

Paso 1: Establecer Priores

Antes de investigar, indica lo que crees y por qué:

Hipótesis	Prior	Razonamiento
H1: [causa A]	40%	Más común para este patrón
H2: [causa B]	30%	Plausible dado el entorno
H3: [otro]	30%	Cobertura general

Los priores deben sumar 100%. Si no puedes asignar probabilidades, investiga primero.

Paso 2: Observar Evidencia

Documenta lo que encontraste — sé específico sobre la fiabilidad:

• ¿Qué observaste exactamente?
• ¿Qué tan fiable es? (salida de prueba > mensaje de registro > informe de usuario > corazonada)
• ¿Podrían múltiples hipótesis explicar esto?

Paso 3: Actualizar Creencias

Para cada hipótesis, pregúntate: ¿Qué tan probable es esta evidencia si esta hipótesis fuera cierta?

La dirección de la actualización importa más que el cálculo:

• Evidencia fuertemente predicha por H1 → la probabilidad de H1 aumenta
• Evidencia contradice H2 → la probabilidad de H2 disminuye
• Evidencia igualmente probable bajo todas → sin actualización

Paso 4: Buscar Evidencia Discriminatoria

No recopiles más de lo mismo. Encuentra evidencia que difiera fuertemente entre las hipótesis principales.

Si H1 y H3 están cerca: "¿Qué vería si H1 es cierta pero no si H3 es cierta?" Luego verifica eso.

Paso 5: Declarar Confianza

Confianza	Acción
90%+	Procede con la corrección, monitorea
70-90%	Procede, agrega verificación de respaldo
50-70%	Prueba la hipótesis antes de comprometerte
<50%	Necesitas más evidencia, no adivines

Nunca expreses certeza binaria cuando la evidencia está incompleta. Usa "muy probable", "plausible pero poco probable", "vale la pena investigar".

Falacias Comunes

Falacia	Ejemplo	Corrección
Descuido de la tasa base	"La prueba falló → el código está roto"	¿Con qué frecuencia fallan las pruebas por otras razones?
Sesgo de confirmación	"Debe ser una condición de carrera, busquemos evidencia de carrera"	Busca activamente evidencia EN CONTRA de tu hipótesis principal
Anclaje	"La última vez fue el caché, probablemente sea el caché otra vez"	Establece priores desde el contexto actual, no del error de ayer

---

Después del Análisis: Acciones Inmediatas

IMPORTANTE: Después de completar el análisis anterior, DEBES inmediatamente:

1. Actualizar spec/guides - No solo enumeres tareas pendientes, actualiza realmente los archivos relevantes:

   • Si es un problema entre plataformas → actualiza cross-platform-thinking-guide.md
   • Si es un problema entre capas → actualiza cross-layer-thinking-guide.md
   • Si es un problema de reutilización de código → actualiza code-reuse-thinking-guide.md
   • Si es específico del dominio → actualiza backend/*.md o frontend/*.md

2. Sincronizar plantillas - Después de actualizar .trellis/spec/, sincroniza con src/templates/markdown/spec/

3. Confirmar las actualizaciones de especificaciones - Este es el resultado principal, no solo el texto del análisis

El análisis no vale nada si se queda en el chat. El valor está en las especificaciones actualizadas.