caohaotiantian/three-loop-workflow

Flujo de Trabajo de Tres Fases

Plan → Build → Close, a una profundidad elegida según los riesgos.

Asume la implementación asignada: su plan, cambios, evidencia, revisión y reparaciones. El implementador puede ser el padre o un ejecutor asignado. Cuando existe un coordinador, deja con él la asignación de tareas, dependencias, interfaces compartidas y la propiedad de la integración. Solicita los roles necesarios o cambios de programación a ese coordinador. No coordines otras tareas de forma recursiva. Dirige las solicitudes de decisión del usuario a través del coordinador. Sin coordinador, gestiona el cambio y los roles requeridos directamente. La profundidad de implementación y el modo de ejecución son independientes. La ejecución directa no elimina la revisión requerida.

Restricciones duras, las únicas reglas que no son predeterminadas:

1. Un cambio por encima de Direct es revisado por un contexto que no lo escribió; solo cuando no haya ninguno disponible, la transferencia lo indica (sección 5).
2. Ejecuta las verificaciones del proyecto. Una verificación que no se pudo ejecutar no es una verificación que pasó.
3. La transferencia reporta lo que se observó, no lo que se pretendía.
4. Un cambio sobre quién puede acceder a qué (autenticación, autorización, secretos, una nueva ruta para entrada no confiable) nunca es Direct.
5. Una acción fuera del repositorio que no se puede deshacer espera al usuario: enviar a una rama compartida, desplegar, escribir datos reales, enviar cualquier cosa.

Todo lo demás es un valor predeterminado: abandona uno solo por una razón explícita. La guía del proyecto anula cualquier valor predeterminado, y los medios son tuyos.

Lee la guía del proyecto (AGENTS.md, CLAUDE.md) para sus comandos de verificación y los archivos que trata como contratos; donde no nombre ninguno, derívalos del repositorio y di lo que inferiste. Las verificaciones provienen de la configuración de compilación y CI; los contratos son lo que se consume fuera de este repositorio o se persiste: APIs públicas, esquemas, CLIs, formatos de cable, datos almacenados.

Aplica las reglas de tipo de texto, idioma y visuales en references/writing.md a la escritura de esta tarea.

1. Profundidad

Toma la profundidad más ligera que corresponda.

• Direct: una edición pequeña obvia cuya corrección es visible o está cubierta por una verificación existente. Un cambio de comportamiento no trivial es Standard o Deep, incluso con pruebas. Una corrección de error tipográfico puede ser Direct. Un valor predeterminado cambiado no. Haz el cambio y ejecuta las verificaciones. No se requiere plan ni revisor. Reporta el cambio, verificaciones, resultados y ausencia de revisión en una línea.

• Standard: el valor predeterminado para cambios de comportamiento.

• Deep: solo cuando se activa un disparador:

  1. un cambio disruptivo en un contrato consumido fuera de este repositorio;
  2. un efecto irreversible fuera del repositorio: una migración de datos persistentes, dinero, cualquier cosa enviada a un tercero;
  3. una regla cambiada en un archivo que el proyecto trata como contrato;
  4. alternativas que se comprometen con diferentes estructuras.

  Entonces lee references/deep.md.

Una esquina riesgosa eleva su propia profundidad, nunca la profundidad de todo el cambio. Eleva la profundidad tú mismo, incluso cuando la compilación revela un disparador; solo el usuario la reduce. Antes de reducirla, recomienda tu profundidad. Para alguien nuevo en este flujo de trabajo, muestra lo que este cambio saltaría y el fallo que quedaría abierto. Si insisten, síguelos sin renunciar a una restricción dura.

2. Plan

En Standard y Deep, antes de la primera edición, escribe el Objetivo, los No-objetivos que te tentaron, y Aceptar, la evidencia (sección 4).

Escala el plan y la revisión según el cambio.

Agrega Decisiones solo en bifurcaciones reales: las opciones, incluida la más pequeña, y por qué ganó la ganadora.

Escríbelo en .agent/<tarea>/plan.md, un directorio por tarea, y confirma los archivos con el cambio, a menos que el proyecto tenga su propia convención. Si .agent está en .gitignore, deja esa entrada y no fuerces la adición de los archivos.

Para trabajo asignado, usa la ruta del plan proporcionada y referencia el alcance compartido y los criterios de aceptación. Mantén los detalles de implementación allí. Deja los registros globales de tareas con el coordinador. Preserva los directorios de tareas canónicos existentes. Para planes delegados, usa por defecto .agent/<tarea>/tasks/<id-porcion>/plan.md.

Cuando dos lecturas de la solicitud necesiten trabajo diferente, indica la tuya en el Objetivo, muéstralo junto con Aceptar al usuario, y espera; si nadie puede responder, procede con tu lectura y márcala como no confirmada en la transferencia. Pregunta sobre decisiones reales de producto, alcance o riesgo con opciones, una recomendación y una justificación, nunca decidas en silencio; registra la respuesta en el plan.

Cuando se desconoce la causa de un defecto, encontrarlo es la tarea: su Aceptar es una reproducción; planifica la corrección después de ella.

3. Construcción

• Cada línea cambiada se remonta al Objetivo o una Decisión. Sin abstracción, configurabilidad ni manejo de errores que nadie necesite.
• Si el código, o una corrección, contradice el plan, detente y corrige el plan abiertamente, no al final.
• Mantente dentro de los archivos e interfaces asignados. Si estos necesitan cambios, pausa el trabajo afectado y solicita una asignación revisada.
• Lectura en paralelo, escritura aislada. Usa un árbol de trabajo separado para cada escritor concurrente (references/parallel.md).
• Para trabajo de integración, ejecuta verificaciones y revisa contra el cambio fusionado. Las verificaciones de porciones aprobadas no establecen aceptación integrada.
• Cuando un documento cita una cifra que produce un comando, cita el comando junto a la cifra, o haz que una verificación lo recalcule.

Para trabajo duradero, almacena los resultados de las verificaciones en evidence/checks.md junto al plan. Registra criterios, comandos, revisiones, resultados, enlaces de evidencia y condiciones de invalidación. Almacena hallazgos, triaje, identidad del revisor y rondas de reparación en evidence/review.md.

4. Evidencia

• Aceptar nombra la evidencia real más barata que fallaría sin el cambio: una verificación existente que se vuelve verde, una nueva prueba, o el resultado observado. Di cómo se ve un fallo.
• No se requiere una nueva prueba unitaria por defecto. Escribe una donde el comportamiento sea lógica que una prueba fija económicamente y valga la pena proteger contra una regresión. Es la verificación incorrecta para renderizado de UI y diseño, cableado y pegamento, configuración, llamadas delgadas a servicios externos, scripts únicos y prosa: observa el resultado en su lugar.
• Donde una persona hace clic, escribe o llama, un contexto que no escribió el cambio lo maneja y reporta lo que vio. Dale la ruta y el fallo, no el diff ni tu relato. Una contradicción es un hallazgo. Sin ese contexto: maneja tu mismo y pega lo que viste. Maneja una superficie prohibida en algún lugar seguro y nombra la brecha. No manejado significa no verificado.
• Donde la salida se lee en lugar de ejecutarse (documentos, texto de ayuda, una especificación), la evidencia es una lectura en frío de los archivos terminados por un lector sin contexto del cambio: léelo como producto, no como diff.
• Un fallo intermitente es en sí mismo una reproducción y la evidencia discriminante. No vuelvas a ejecutar el fallo de este cambio hasta que pase, y no exijas una reproducción determinista antes de tratarlo como tal. Uno que este cambio no causó es un seguimiento nombrado, no corregido dentro de este cambio.
• Ejecuta las verificaciones antes de la revisión, las que cubren el cambio después de cada corrección, y el conjunto completo una vez antes de la transferencia. Pega las líneas de aprobado/fallido, no los registros completos. Todo lo omitido, o el verde comprado debilitando una prueba, no es un aprobado.

5. Revisión

El revisor recibe el cambio completo (o, para un cambio construido por fases, la fase completa), el plan y el repositorio, no tu resumen o razonamiento. Completo significa cada archivo que el cambio agrega, modifica o elimina, incluidos los archivos nuevos no rastreados; una revisión de un diff vacío o incompleto no es una revisión limpia. Direct no necesita revisor; Standard obtiene uno.

Revisiones o lecturas independientes no disponibles: usa primero los contextos independientes disponibles. Para roles faltantes, inspecciona los artefactos completos especificados anteriormente, no tu recuerdo del trabajo. Aplica los resúmenes de los roles faltantes en una sola pasada de auto-revisión. Etiquétalo como "auto-revisión, no independiente" y reporta los roles independientes faltantes. Ofrece al usuario los resúmenes para ejecutar en otro lugar. Este respaldo no anula requisitos más estrictos del usuario, proyecto o anfitrión.

Entrega este resumen textual:

Revisa este cambio contra su plan. Reporta cada hallazgo con archivo:línea,
marcado como bloqueante (comportamiento incorrecto, un contrato roto, trabajo fuera del plan)
o no bloqueante. No modifiques el código.
1. ¿Dónde se rompe? Entrada inesperada, entrada hostil donde toca la confianza,
   fallos de lo que llama, hechos asumidos desde fuera del diff.
2. ¿Se debilitaron las pruebas existentes?
3. ¿El nuevo comportamiento está demostrado por evidencia, una prueba o un resultado
   observado, que falla sin el cambio? No pidas nada más.
4. ¿Algo está fuera del Objetivo o dentro de un No-objetivo?
5. ¿El plan en sí mismo está equivocado?

Triaje antes de corregir. Confirma cada hallazgo contra el código citado. Rechaza lecturas erróneas y hallazgos que pidan trabajo que un No-objetivo excluye, una línea cada uno. Una prueba faltante es no bloqueante a menos que proteja un error de corrección confirmado. El cambio se cierra cuando no queda ningún hallazgo bloqueante confirmado.

Revisar el cambio de otra persona: el mismo resumen, con su descripción como plan; los No-objetivos faltantes son un hallazgo. Haz triaje, luego entrega los hallazgos confirmados al autor; no los corrijas.

6. Corregir y detener

• Una corrección repara lo que cita un hallazgo confirmado, en su causa raíz, en todas partes donde ocurre el mismo defecto.
• Nueva maquinaria es nuevo trabajo: una nueva verificación, arnés, guarda, abstracción o archivo de prueba se convierte en un seguimiento nombrado, no parte de la corrección. Agrega una prueba fallida solo para un error de corrección confirmado, y extiende un archivo de prueba existente.
• Después de cada corrección, el revisor vuelve a verificar solo la corrección: ¿se resolvieron los hallazgos citados y la corrección introdujo algo? Una corrección más su re-verificación es una ronda.

Detente y pregunta al usuario cuando una ronda deja los hallazgos confirmados sin cambios, una corrección crece hacia archivos o maquinaria que el plan no cubría, o quedan hallazgos bloqueantes después de la tercera ronda. Trae los hallazgos no resueltos textualmente, lo que se intentó, dónde se rompe con salida real, las opciones (revisar el plan, aceptar un riesgo documentado, descartar el elemento como seguimiento, dividir la maquinaria) y tu recomendación. Nunca bajes el listón en silencio.

7. Cierre: la transferencia

La transferencia es la descripción final del cambio. Un HANDOFF.md de un coordinador proporciona instrucciones de reanudación. Aplica las reglas de lecturas selectivas y ciclo de vida de registros en references/writing.md. Con un coordinador, devuelve candidatos de memoria con origen y deja las actualizaciones compartidas con él.

En Standard y Deep, la descripción del cambio lleva:

• el Objetivo, como lo que un usuario puede hacer ahora, y los No-objetivos;
• Aceptar, y lo que la evidencia realmente mostró;
• lo que no se pudo verificar, y por qué;
• quién lo revisó, o "auto-revisión, no independiente", o que no hubo revisión, y lo mismo para una ruta que alguien maneja;
• una profundidad que el usuario redujo, y lo que le mostraste antes de que insistiera;
• hallazgos no bloqueantes no corregidos, una línea cada uno;
• riesgo residual;
• en Deep, la reversión tal como está ahora.

Para trabajo asignado, devuelve rutas de artefactos y revisiones, evidencia, estado de revisión, solicitudes no resueltas, y comandos modificadores activos o desconocidos. Reporta la finalización local al coordinador. No reclames la finalización de la tarea general.

Las herramientas de revisión, seguridad u orquestación que el usuario agrega complementan la revisión independiente, nunca la reemplazan.