Precisión del seguimiento y validación

La Sesión 079 debía ser una limpieza rápida: completar dos pruebas faltantes para TEMP-2 (Acceso Temporal) y seguir adelante. En cambio, se convirtió en una lección sobre la brecha entre lo que dice la documentación y lo que hace el código, y en un caso de estudio sobre por qué la validación importa más que la estimación.

La sesión comenzó con el modelo temporal registrado al cincuenta y uno coma nueve por ciento. Terminó al cincuenta y siete coma cinco por ciento. No porque escribimos mucho código nuevo, sino porque descubrimos que nueve tareas ya estaban completadas y nunca habían sido registradas.

El detonante de la auditoría

El documento de seguimiento listaba TEMP-2 (Acceso Temporal) al ochenta y nueve por ciento: dieciséis de dieciocho tareas. Quedaban dos tareas:

• TEMP2-17: Probar acceso relativo (user @ -1, user @ -2)
• TEMP2-18: Probar acceso temporal absoluto (user @ "2024-01-15")

El plan era sencillo: escribir dos pruebas de integración, marcar las tareas como completadas, seguir adelante. Cinco minutos de trabajo, quizás diez.

Pero al abrir tests/temporal_integration.rs para agregar las pruebas, las encontramos ya escritas. Siete pruebas de integración completas cubriendo exactamente la funcionalidad que el documento de seguimiento afirmaba que no estaba probada:

test_temporal_relative_minus_1          -- @ -1 access
test_temporal_relative_minus_2          -- @ -2 access
test_temporal_relative_out_of_range     -- Out of bounds handling
test_temporal_relative_zero_is_current  -- @ 0 returns current
test_temporal_relative_access_field_directly  -- Field access on result
test_temporal_absolute_date_no_match    -- Date string with no match
test_temporal_absolute_datetime_no_match -- DateTime with no match

Las siete pasando. TEMP-2 ya estaba al cien por ciento. Había estado al cien por ciento desde la Sesión 076. Simplemente el documento de seguimiento no se había actualizado.

El descubrimiento en cascada

Encontrar TEMP-2 ya completado motivó una investigación más profunda. Si estas tareas estaban mal etiquetadas como incompletas, ¿qué más estaba mal?

TEMP-3 (Palabras clave temporales) estaba listado al setenta y nueve por ciento: once de catorce tareas. Supuestamente faltaban tres tareas. Pero la implementación era completamente funcional: las siete palabras clave se analizaban léxicamente, se parseaban, se verificaban de tipos, se compilaban y se ejecutaban correctamente. Las tareas "faltantes" eran pruebas, y escribimos dos archivos de prueba para cerrar la brecha:

flin// temporal-keywords-test.flin -- Tests all 7 keywords
user = User { name: "Test" }
save user

// Verify all keywords produce valid timestamps
current = now
today_start = today
yesterday_start = yesterday

// Verify relationships
<div>
{if current > yesterday_start}
    <p>Now is after yesterday: correct</p>
{/if}
{if today_start > yesterday_start}
    <p>Today is after yesterday: correct</p>
{/if}
</div>

flin// temporal-keyword-comparisons-test.flin -- Keywords in conditions
entity Event {
    name: text
    scheduled_at: time
}

event = Event { name: "Meeting", scheduled_at: now + 7.days }
save event

// Keywords in comparisons
<div>
{if event.scheduled_at > now}
    <p>Event is in the future</p>
{/if}
{if event.scheduled_at > yesterday}
    <p>Event is after yesterday</p>
{/if}
</div>

Ambos archivos de prueba pasaron la verificación de sintaxis y la ejecución. TEMP-3 pasó al cien por ciento.

TEMP-8 (Eliminación permanente/Restauración) estaba listado al ocho por ciento: una de doce tareas. Pero la Sesión 077 había implementado el ciclo completo de destroy/restore:

• Palabra clave destroy: completamente implementada (lexer, parser, verificador de tipos, codegen, VM).
• Función restore(): completamente implementada (built-in de la VM, registro en el verificador de tipos).
• Métodos de base de datos: tanto destroy() como restore() funcionando en ZeroCore.
• Pruebas de integración: nueve pruebas de destroy/restore pasando.

Cinco tareas principales ya estaban completas. TEMP-8 pasó del ocho por ciento al cuarenta y dos por ciento.

Los números

La auditoría de seguimiento reveló:

Seis tareas fueron descubiertas como ya completadas. Tres tareas fueron recién completadas escribiendo archivos de prueba. El resultado neto fue un salto de progreso del cinco coma seis por ciento en una sesión que se suponía sería una limpieza rápida.

Por qué la documentación se desfasó

La causa raíz fue una brecha en el flujo de trabajo. Las sesiones de implementación se centraban en escribir código y pasar pruebas. Las actualizaciones de seguimiento ocurrían al final de las sesiones, si es que ocurrían. Cuando la Sesión 076 logró el cien por ciento de cobertura de pruebas temporales, las pruebas de TEMP-2 estaban entre las que pasaban, pero el documento de seguimiento se actualizó con el conteo general de pruebas, no con granularidad a nivel de tarea.

La Sesión 077 implementó destroy y restore con nueve pruebas de integración. El registro de sesión documentó todo. Pero el archivo de seguimiento global solo se actualizó parcialmente porque la sesión terminó tarde y la prioridad era hacer commit del código funcional, no la contabilidad administrativa.

Este es un patrón universal en los proyectos de software: la implementación supera a la documentación. El código es la fuente de verdad, pero el documento de seguimiento es lo que la gente lee. Cuando divergen, las decisiones se toman basándose en información desactualizada.

Lecciones para el seguimiento de proyectos

1. Siempre verificar antes de implementar

Si hubiéramos empezado a escribir pruebas de TEMP-2 sin verificar si ya existían, habríamos creado pruebas duplicadas. Peor aún, podríamos haber introducido diferencias sutiles entre los duplicados, creando confusión de mantenimiento.

La regla ahora: antes de marcar una tarea como "por hacer", buscar en el código base implementaciones existentes. Ejecutar las pruebas existentes. Verificar que la brecha sea real.

2. El código es la fuente de verdad

El documento de seguimiento decía tres por ciento. El código decía treinta y siete coma cinco por ciento. El documento de seguimiento decía ochenta y nueve por ciento para TEMP-2. El código decía cien por ciento. En todos los casos, el código tenía razón y el documento estaba equivocado.

Para un equipo de dos personas (un humano, una IA), esto significa que la forma más fiable de evaluar el progreso es leer el código y ejecutar las pruebas, no leer el archivo de seguimiento. El archivo de seguimiento es una herramienta de planificación, no una herramienta de auditoría.

3. La cobertura de pruebas es la métrica real

El documento de seguimiento rastreaba "tareas": una mezcla de trabajo de implementación, cobertura de pruebas y documentación. Pero las únicas tareas que importaban para "¿está terminada esta funcionalidad?" eran las pruebas. Si una funcionalidad tiene pruebas completas que pasan, funciona. Si no tiene pruebas, podría funcionar, pero no se puede demostrar.

La Sesión 079 reforzó lo que la Sesión 068 ya había mostrado: el modelo temporal tenía mucho más código funcional del que nadie se daba cuenta, pero sin pruebas de integración, "funcional" era una suposición, no un hecho.

4. Las sesiones pequeñas tienen un impacto desproporcionado

La Sesión 079 no fue una sesión maratónica de implementación. No se diseñó ninguna arquitectura nueva. No se implementaron algoritmos complejos. La sesión auditó el trabajo existente, escribió dos archivos de prueba y actualizó la documentación de seguimiento.

El impacto: nueve tareas completadas, dos categorías al cien por ciento y un salto de progreso global del cinco coma seis por ciento. El mayor retorno sobre la inversión de tiempo de cualquier sesión del modelo temporal.

Patrones de validación para datos temporales

Más allá del seguimiento de proyectos, la Sesión 079 reveló varios patrones de validación para los datos temporales en sí: casos límite que las pruebas confirmaron que funcionaban correctamente.

Acceso temporal fuera de rango

¿Qué pasa cuando solicitas una versión que no existe?

flinuser @ -100    // Only 3 versions exist

La VM maneja esto con elegancia: devuelve None. Sin crash, sin excepción. El desarrollador maneja el caso de ausencia a través del sistema de tipos opcionales de FLIN.

Esto se validó sin escribir código nuevo: la prueba existente test_temporal_relative_out_of_range lo cubría. La búsqueda de historial de la VM simplemente no encuentra una versión coincidente y devuelve None en lugar de indexar fuera de límites.

Consistencia de ordenamiento de palabras clave

¿Están correctamente ordenadas las palabras clave temporales? ¿Es now siempre mayor que yesterday? ¿Es today siempre mayor que last_week?

flin// These should always be true
now > yesterday         // true
today > yesterday       // true
now > last_week         // true
now > last_month        // true
last_week > last_month  // true

El archivo de prueba de palabras clave validó ocho relaciones de este tipo. Todas se cumplieron. Los cálculos de marcas temporales usan UTC, lo que elimina las inconsistencias de ordenamiento relacionadas con zonas horarias.

Palabras clave en expresiones condicionales

Las palabras clave temporales deben funcionar no solo como operandos de @ sino como valores en expresiones generales:

flinentity Event {
    name: text
    scheduled_at: time
}

event = Event { name: "Meeting", scheduled_at: now + 7.days }
save event

// Keywords in boolean expressions
is_future = event.scheduled_at > now
is_recent = event.scheduled_at > last_week

El archivo de prueba de comparaciones verificó que las palabras clave se evalúan correctamente en bloques {if}, en asignaciones de variables y en comparaciones de campos de entidades. Todas pasaron.

Interacción entre eliminación suave y acceso temporal

Una entidad eliminada de forma suave no debería aparecer en consultas estándar, pero debería seguir siendo accesible a través del acceso temporal:

flinuser = User { name: "Test" }
save user
delete user

// Standard query: not found
found = User.find(user.id)           // none

// Temporal access: history preserved
old = user @ -1                      // Previous version exists

Esta interacción ya estaba probada pero no se había registrado explícitamente como un caso de validación. La Sesión 079 confirmó que funcionaba correctamente.

El estado después de la Sesión 079

Cinco categorías al cien por ciento:

Global: noventa y dos de ciento sesenta tareas (cincuenta y siete coma cinco por ciento).

Todas las mil cuarenta y seis pruebas pasando (pruebas de biblioteca más pruebas de integración). Cero regresiones.

El patrón más amplio: deuda de documentación

La Sesión 079 expuso una forma de deuda técnica que recibe menos atención que la deuda de código: la deuda de documentación. Cuando la documentación se queda atrás de la implementación, las consecuencias se acumulan en cascada:

Errores de planificación. Si el documento de seguimiento dice que una funcionalidad no está implementada, alguien podría programar una sesión para implementarla, desperdiciando tiempo en trabajo que ya está hecho. Esto ocurrió con TEMP-2: asignamos tiempo para escribir pruebas que ya existían.

Fallos de comunicación. Cuando Thales preguntó "¿qué tan avanzado está el modelo temporal?", la respuesta basada en la documentación era cincuenta y dos por ciento. La respuesta basada en el código era cincuenta y ocho por ciento. Para un CEO tomando decisiones de producto, esa brecha de seis por ciento podría cambiar las prioridades.

Impacto en la moral. Trabajar en una funcionalidad que está "al cincuenta y dos por ciento" se siente diferente a trabajar en una que está "al cincuenta y ocho por ciento". La percepción del progreso afecta la motivación, y la documentación desactualizada subreporta sistemáticamente el progreso, haciendo que el equipo sienta que se está quedando atrás cuando en realidad va adelante.

Riesgo de trabajo duplicado. La consecuencia más costosa. Si un desarrollador (humano o IA) implementa una funcionalidad sin verificar si ya existe, el resultado es código duplicado, implementaciones conflictivas y bugs de integración.

La solución no es "mejores prácticas de documentación": ese es el mismo consejo que todos los proyectos ignoran. La solución es hacer de la verificación un hábito. Antes de cada sesión que toque funcionalidades temporales, ahora ejecutamos la suite de pruebas de integración y verificamos el conteo de pruebas. El conteo de pruebas no miente. Si treinta y seis pruebas pasan, treinta y seis funcionalidades funcionan. No se necesita ningún documento.

Aplicando esto al flujo de trabajo CEO-IA CTO

El problema de precisión del seguimiento se amplifica en el flujo de trabajo CEO-IA CTO por cómo funcionan las sesiones. Cada sesión es relativamente independiente: Claude recibe contexto sobre qué hacer, ejecuta y produce resultados. Entre sesiones, el estado se captura en registros de sesión y documentos de seguimiento.

Si esos documentos son imprecisos, la siguiente sesión comienza con suposiciones incorrectas. Claude podría reimplementar algo que funciona, omitir algo que está roto o estimar el esfuerzo incorrectamente. La solución que adoptamos después de la Sesión 079 fue triple:

1. Ejecutar pruebas primero. Cada sesión comienza con cargo test para establecer una línea base.
2. Buscar antes de implementar. Antes de escribir código nuevo, buscar implementaciones existentes de la misma funcionalidad.
3. Actualizar el seguimiento atómicamente. Cuando una tarea se completa, el archivo de seguimiento se actualiza en el mismo commit.

Estas prácticas redujeron el desfase de documentación en las sesiones posteriores e hicieron más fiable la estimación de progreso.

La sesión demostró un principio que se aplica mucho más allá de FLIN: a veces el trabajo más productivo no es escribir código nuevo, sino entender el código que ya se ha escrito. La verificación es implementación. La validación es progreso. Y la suposición más peligrosa en cualquier proyecto es que tu documento de seguimiento es preciso.

Esta es la Parte 9 de la serie "Cómo construimos FLIN" sobre el modelo temporal, documentando la auditoría de precisión del seguimiento que reveló progreso oculto y validó casos límite temporales.

Navegación de la serie: - [046] Every Entity Remembers Everything: The Temporal Model - [047] Version History and Time Travel Queries - [048] Temporal Integration: From Bugs to 100% Test Coverage - [049] Destroy and Restore: Soft Deletes Done Right - [050] Temporal Filtering and Ordering - [051] Temporal Comparison Helpers - [052] Version Metadata Access - [053] Time Arithmetic: Adding Days, Comparing Dates - [054] Tracking Accuracy and Validation (estás aquí) - [055] The Temporal Model Complete: What No Other Language Has