[🛠] Operations Automation #4: Una estructura para evitar estados obsoletos modificando menos documentos

✨ Resumen de GPT-5.6 Sol

Un registro de cómo abandoné la copia de cada cambio de estado en varios documentos y reorganicé su actualización con un único owner para el estado variable, downstream condicionales y phase checkpoints.

Cuantos más documentos actualizaba, más se dividía el estado actual

Después de comprimir el contexto de una tarea larga o de pasarla a otra session, en ocasiones se retomaba como estado actual la siguiente acción escrita en un documento antiguo. Para evitarlo, durante un tiempo actualicé todos los documentos que parecían relacionados cada vez que cambiaba el estado.

Repetía el mismo hecho terminado y la siguiente acción en el README, el router de documentos, los requisitos, la dirección actual, el Runbook y el TODO. Parecía que todo estaría seguro mientras no olvidara ningún documento.

Pero desde el momento en que escribía un cambio de estado en seis lugares, tenía que mantener los seis siempre idénticos. Un documento se quedaba en el estado anterior al deploy y otro afirmaba que ya había terminado la verificación en un dispositivo real. Actualizar muchos documentos no evitaba que el estado quedara obsoleto: creaba nuevos estados obsoletos.

Además, al modificar varios documentos y dejar un commit después de cada pequeña verificación, el Git history quedó fragmentado. Se veía mejor cuántas veces había sincronizado el texto que dónde terminaba realmente la implementación.

Un solo documento pasó a ser el owner del estado variable

El problema no era la cantidad de documentos, sino que varios documentos fueran owners del mismo hecho. Por eso asigné primero un único owner a cada tipo de hecho.

Hecho que cambia	owner	Condición para modificar otros documentos
Runtime actual, blocker, phase y siguiente acción	canonical current-state snapshot	No se copia en otros documentos
Decisiones estables del producto, alternativas prohibidas y Goal activo	Documento current-direction	Solo cuando cambia la decisión del producto o el propio Goal
Comportamiento, datos, autorización y acceptance	requirements o contract	Solo cuando cambia el contrato de comportamiento del usuario o del sistema
Procedimiento operativo, gate, rollback y recovery	Runbook	Solo cuando cambia el procedimiento que debe seguir quien opera el sistema
Relaciones entre documentos, etapa del producto y punto de entrada de ejecución	README o router	Solo cuando cambia la ruta de navegación o la relación del producto
Comandos detallados, logs y verificación de workers	report, artifact y Git evidence	Los documentos aggregate solo conservan la conclusión y los enlaces a la evidencia

La clave es separar «estar relacionado» de «ser owner». Que termine un deploy no obliga a modificar los requisitos. Si durante el deploy cambia el procedimiento operativo de rollback, se modifica el Runbook; si también cambia el contrato de comportamiento, entonces se modifican los requirements.

El README y el router tampoco persiguen la revision actual, el estado de los dispositivos o la siguiente acción. Su función es indicar de forma estable qué hay que leer y desde dónde debe ejecutarse.

Separé la actualización inmediata del durable checkpoint

Tener un único owner no significa posponer la actualización del documento hasta el final de una phase. Si aparece nueva evidencia o cambian el estado del Runtime, el blocker, la prioridad o la siguiente acción, actualizo el canonical current-state snapshot antes de continuar con la implementación. Así, aunque la tarea se comprima o se entregue a mitad de camino, la siguiente session puede recuperar el estado real desde un solo lugar.

En cambio, no creo un commit cada vez que cambia una línea del estado. Solo vuelvo a revisar el current-state y creo un checkpoint en los límites desde los que se puede hacer una review independiente y retomar el trabajo.

• Cuando termina la implementación
• Cuando terminan el deploy y la verificación posterior
• Cuando hay un resultado E2E en un dispositivo real o en el punto de entrada del usuario, o cuando se confirma un blocker
• Cuando hay que entregar el trabajo por una interruption o un handoff

La actualización inmediata protege la seguridad del resume; el phase checkpoint permite revisar y revertir un conjunto de cambios. Tratar ambos como una sola regla fue lo que multiplicó los micro-event commits.

En un trabajo sin permiso para hacer commit, la regla es todavía más sencilla. Terminar la review no permite crear un estado COMMITTED o CLOSED. El candidato de integración permanece en estado freeze y no se registra como una finalización durable hasta que exista un checkpoint real.

La verificación de los workers queda en los reports, fuera de los documentos aggregate

En el trabajo en paralelo, cada worker deja comandos ejecutados, resultados de comprobaciones, hunk solapados y restricciones pendientes. Si vuelvo a pegar todo eso en el TODO raíz, el README y los requisitos, solo aumento la cantidad de documentos que debe leer el coordinator.

La evidencia detallada de cada worker queda en un immutable report y en el Git diff. El current-state solo conserva la conclusión integrada, el impacto actual y la ruta de la evidencia. El coordinator revisa los reports uno por uno, pero no trata cada report como un commit. Varios reports que forman parte de la misma phase pueden compartir un checkpoint después de la verificación integrada.

Con esta separación, los documentos aggregate son más breves sin que desaparezca la verificación detallada. La siguiente session lee primero el estado actual y solo baja a los reports enlazados y a la Git evidence cuando necesita revisar el fundamento de una decisión.

El orden de resume contradecía la regla de owner

Después de ordenar las reglas, revisé el flujo completo y encontré una contradicción sorprendentemente básica. El procedimiento de inicio indicaba leer primero el README y después todo.md.

El README decía que no debía copiarse el estado variable, pero el flujo real de resume leía el router antes que el current-state. Si quedaba texto obsoleto en el router, la primera decisión ya podía avanzar en una dirección equivocada.

Por eso cambié el orden de inicio. Primero se consultan en el canonical current-state el Runtime actual, el blocker, la phase y la siguiente acción. Después se usan el README y el router de documentos para localizar los límites del repository y el leaf document necesario. Las decisiones estables del producto se leen en current-direction, y el contrato de comportamiento real, en requirements.

No bastaba con añadir una tabla de owners de documentos. El orden de lectura real, tanto para una persona como para un Agent, también tenía que seguir esas relaciones de ownership.

Alcance actual y límites pendientes

Esta estructura ya se ha incorporado a las reglas de trabajo compartidas, al routing documental de Operations Automation, al manifest de documentación de cambios y al protocol de coordination paralela. Han pasado el skill validator, la comprobación de sincronización documental y la comprobación del diff. Sin embargo, los cambios actuales todavía están en el local working tree; aún no se han llevado a un commit ni se han desplegado.

Tampoco reescribí retroactivamente todos los documentos existentes. Conservé el historial y los reports detallados, y solo reduzco a una referencia al owner los hechos de current-state que entren en conflicto entre documentos active. Antes que eliminar la existencia de documentos antiguos, era más importante dejar de leerlos como authority del trabajo actual.

Ahora no juzgo la actualización documental por la cantidad de lugares modificados. El criterio es si, tras una compresión o un handoff, basta con leer un solo lugar para no equivocarse sobre la phase actual y la siguiente acción, y si la evidencia detallada puede volver a rastrearse cuando sea necesaria.