noahwhite/engineering-workflow

Flujo de trabajo de ingeniería

Un proceso basado en porciones, dirigido por pruebas y con puertas de validación, desde la historia hasta el build desplegado.

Triaje de historia -> en progreso -> porciones, cada una por TDD -> puerta adversarial pre-PR (escalar al bucle de dos lentes solo cuando sea necesario) -> PR a la rama de integración -> revisores opcionales (nunca bloqueantes) -> revisión de registro (revisor, luego adjudicador) -> remediar y volver a revisar hasta que esté limpio en HEAD -> fusionar -> desplegar y verificar -> revisión de despliegue

No omitir una puerta porque el cambio parezca simple.

Antes del paso 1

1. Leer references/profile.md, luego la superposición de este skill y cada superposición de capacidad que profile.overlays nombre.
2. Leer references/todo-tracking.md y crear la lista de tareas detallada (un elemento por porción, prueba, ronda de puerta, ronda de revisión, despliegue, verificación y espera). references/runtimes.md mapea la lista de tareas, los subagentes, el directorio temporal y las preguntas al usuario a tu entorno de ejecución.

Los pasos siguientes son la columna vertebral del flujo de trabajo; los archivos de capacidad contienen las reglas y son autoritativos donde se superponen:

• references/linear.md: ciclo de vida de la historia, triaje y Definición de Listo, transiciones de estado (pasos 1, 5, 12).
• references/engineering-practice.md: diagnóstico, TDD, correcciones duraderas, calidad de pruebas (pasos 2, 3, 6, 8) y retirar una nota de memoria cuando un cambio escribe su regla en un skill.
• references/github.md: ramas, árboles de trabajo, commits, firma, PRs, fusión, promoción, atribución (pasos 2, 5, 10).
• references/code-review.md: la revisión de registro, revisores opcionales, manejo de hallazgos, seguimiento del PR (pasos 6 a 10).
• references/merge-approval.md: el protocolo delegado de aprobación de fusión: solicitar, activar, esperar, aprobar o rechazar, y volver a solicitar cuando la cabeza cambie (paso 10).
• references/secrets.md: cada vez que el cambio toque credenciales.

Ejecutar cada script en scripts/ por su ruta absoluta instalada (<skill dir>/scripts/<name>, donde <skill dir> es el directorio absoluto desde el cual tu runtime cargó este skill) con el directorio actual en el repositorio consumidor; el repositorio consumidor no los contiene. Cada script se dirige al repositorio del directorio actual, o al que --repo <dir> nombre, nunca a su propia ubicación, y se niega a ejecutarse en el propio repositorio de skills a menos que --repo lo nombre.

1. Triaje de la historia

Si la historia no está refinada y puntuada, ejecutar story-refinement primero. Ejecuta el refinamiento independiente, la ronda de aceptación, la puntuación secreta, la verificación de consenso y, cuando la verificación lo requiera, la discusión de alto/bajo y el consenso.

1. Leer la historia completamente: criterios de aceptación, comentarios, problemas vinculados y contexto.
2. Identificar el comportamiento deseado, criterios de aceptación, restricciones, componentes probablemente afectados y estrategia de prueba.
3. Enumerar dependencias del gráfico de relaciones formal, no solo de la prosa: linear issue relation list <ID> lista las relaciones de un problema, mientras que linear issue view --json no las incluye (ver references/linear.md, Triaje).
4. Confirmar que la historia pertenece a este repositorio.
5. Aplicar las reglas de alcance: ningún criterio de aceptación cambiado en ninguna historia (references/linear.md "Criterios de aceptación y alcance"), ninguna omisión clave basada en otra historia (references/engineering-practice.md "Hacer cambios mínimos y duraderos"), y las únicas dos salidas son una "Propuesta de refinamiento (no un CA)" o reportar la historia como bloqueada, como se indica en esas secciones; el paso 5, "Preparar el PR", ítem 4, "Autorevisión contra los criterios de aceptación", los verifica nuevamente.
6. Moverla a profile.tracker.states.in_progress y leerla de nuevo para confirmar. Usar los nombres de estado exactos del perfil; nunca inventar uno.

Si el sistema de seguimiento no se puede actualizar, detenerse y decir que la transición no se realizó; nunca afirmar que se hizo.

2. Planificar porciones

Crear una rama y un árbol de trabajo según references/github.md, desde origin/<rama de integración> (la rama de integración es profile.git.integration_branch) después de un fetch. Dividir la historia en porciones verticales pequeñas, cada una con un objetivo de comportamiento estrecho, pruebas que lo definan, la implementación mínima para pasarlas y refactorización solo una vez que esté en verde. Indicar la secuencia de porciones y la primera porción antes de codificar.

3. TDD por porción

1. RED: escribir una prueba fallida para el comportamiento.
2. GREEN: el código de producción mínimo para pasarla.
3. REFACTOR sin cambiar el comportamiento.
4. Ejecutar las pruebas enfocadas.
5. Ejecutar validación más amplia periódicamente y antes del PR.

Si la arquitectura hace que el TDD estricto sea impráctico para una porción, explicar por qué. Preservar las pruebas y convenciones existentes.

4. Puerta adversarial pre-PR (obligatoria)

Cargar el skill adversarial-review-pipeline y ejecutarlo hasta su finalización en cada revisión; su informe de arbitraje es la salida de esta puerta. No hacer correcciones antes de su fase de búsqueda.

Escalación: el bucle de dos lentes con compuerta

Escalar solo cuando el pipeline no pueda cerrar el diff:

• su ronda de reverificación encuentra un nuevo hallazgo Crítico o Alto, o
• el diff tiene forma de seguridad, migración, concurrencia o ruta de despliegue, o
• el pipeline alcanzó su límite con hallazgos Críticos o Altos no resueltos.

Nunca ejecutar el bucle y el pipeline sobre la misma cabeza. Limitar el bucle a 2 rondas.

El bucle converge en cero hallazgos bloqueantes verificados, no en cero hallazgos: un terminador de cero hallazgos recompensa a los revisores por inventar hallazgos una vez que los reales han desaparecido, y un reparador obligado a actuar sobre cada hallazgo infla el código.

Roles, todos del perfil:

• Lente de corrección: profile.review.pre_pr.hunter (corrección, cableado, seguridad, concurrencia, compatibilidad, brechas de prueba).
• Lente de simplicidad: profile.review.pre_pr.simplicity_reviewer (cambio correcto más pequeño, sobreingeniería, código muerto y defectos que la otra lente pasó por alto).
• Verificador: profile.review.pre_pr.arbiter.
• Reparador: profile.review.pre_pr.fixer.

Un revisor de simplicidad o reparador deshabilitado bloquea la escalación en lugar de omitirla: registrar ": deshabilitado" y detenerse con la escalación no resuelta, porque el bucle no puede completar una ronda sin ambos asientos.

Una ronda tiene tres etapas:

1. Revisión. Ambas lentes revisan git diff origin/<rama de integración>...HEAD en paralelo; el cazador trabaja en un árbol de trabajo desechable separado. Pasar la historia y los criterios de aceptación como referencia de alcance. Solo los hallazgos Críticos o Altos con un escenario de falla concreto bloquean; el resto se registran, nunca se corrigen y nunca bloquean la convergencia. Una salida de revisor que muestre un error de sandbox o permiso, o una lente que no pueda mostrar que leyó el diff y los archivos cambiados, es una revisión fallida, nunca una limpia.
2. Verificar. Un verificador limpio y neutral intenta refutar cada hallazgo bloqueante contra el código y descarta los no confirmados. Debe devolver exactamente un veredicto por candidato; una verificación faltante o parcial deja la puerta no resuelta, nunca limpia.
3. Reparar. El reparador corrige los hallazgos verificados con los que está de acuerdo, rechaza el resto con una razón, ejecuta las pruebas enfocadas y hace commit. Una corrección cuyas pruebas no pasaron no es una corrección: la puerta no está resuelta. No debe agregar módulos, tablas o migraciones, persistencia o abstracciones; un hallazgo que los necesite se escala a un humano. Poner la regla de que un agente ejecuta cada paso de shell como un comando simple con valores literales (references/github.md, Herramientas) en el prompt que se le da al reparador, incluyendo un archivo de prompt cuando el reparador se ejecuta como un comando de shell.

Salidas: convergido (nada bloqueante después de la revisión, o nada sobrevivió una verificación completa); sin progreso (el recuento verificado no disminuyó después de una corrección: detenerse y revisar manualmente); alcance escalado (llevarlo al propietario); una lente ciega, una verificación incompleta, una corrección con pruebas fallidas, el límite de rondas, todo rechazado o sin commit (no resuelto: resolver manualmente en lugar de omitir la puerta).

scripts/adversarial-review-loop.workflow.js es un acelerador opcional específico del runtime para runtimes que ejecutan scripts de flujo de trabajo; su encabezado lista sus argumentos, todos tomados del perfil. En cualquier otro lugar, manejar las rondas manualmente como se indica arriba: generar los dos revisores en paralelo, luego un subagente verificador limpio y neutral, luego reparar (o generar el reparador) y repetir solo mientras aparezcan nuevos hallazgos bloqueantes verificados. Instruir al reparador con la regla de git: ejecutar cada comando de git que cree un commit con la identidad de git ya configurada y, cuando profile.git.signed_commits sea verdadero, la firma ya configurada; nunca pasar -c user.name, -c user.email, --author, GIT_AUTHOR_* o GIT_COMMITTER_*, nunca escribir user.name o user.email con git config, y cuando la firma esté activada nunca pasar -c user.signingkey, -c gpg.* o -c commit.gpgsign; una identidad faltante, una verificación de firma fallida o un commit empujado cuyo .commit.verification.verified sea falso es un fallo de configuración, así que detenerse, no sobrescribir por comando ni escribir git config, no hacer más commits y reportarlo al usuario.

Revisar los commits del reparador

El reparador puede extralimitarse en código que el diff solo consume. Después del bucle:

• Leer cada commit del reparador en git log origin/<rama de integración>..HEAD.
• Si alguno toca archivos fuera del alcance de la historia, resetear a tu último commit real para eliminarlos (nunca hacer force-push a una rama publicada; ver references/github.md), luego adjudicar esos hallazgos manualmente: corregir los que estén dentro del alcance, archivar el resto.
• Un "archivo eliminado" en ese rango puede ser un artefacto de rama desactualizada; hacer rebase sobre la rama de integración obtenida antes de juzgar eliminaciones.
• Nunca empujar los commits del reparador sin leerlos.

No abrir el PR hasta que la puerta haya convergido o sus hallazgos residuales estén explícitamente justificados. Los revisores nunca modifican código; solo el agente implementador o el reparador del bucle hace commits.

5. Preparar el PR

1. Ejecutar el conjunto de pruebas aplicable completo, más los formateadores, linters, comprobaciones de tipo, análisis estático y compilación del repositorio.
2. Inspeccionar git diff origin/<rama de integración>...HEAD después de un fetch.
3. Confirmar que no hay cambios no relacionados ni secretos.
4. Autorevisión contra los criterios de aceptación, y contra el paso 1, "Triaje de la historia", ítem 5 "Aplicar las reglas de alcance" (references/linear.md "Criterios de aceptación y alcance", references/engineering-practice.md "Hacer cambios mínimos y duraderos"): ningún criterio de aceptación cambiado en ninguna historia, ninguna omisión clave basada en otra historia, y cada requisito descubierto o criterio no cumplido llevado a través de una de las dos salidas que esas secciones indican.
5. Abrir el PR contra profile.git.integration_branch con gh pr create --base, siguiendo la plantilla de PR del repositorio. Describir el cambio visible para el usuario, la implementación, las pruebas realizadas y cualquier cosa aceptada o diferida por la puerta.
6. Mover la historia a profile.tracker.states.in_review según references/linear.md.

Atribución: los commits y el PR siguen profile.git.ai_attribution (ver references/github.md). Cuando sea forbid, no agregar ningún trailer de coautor de IA, enlace de sesión o nota de generado-por, incluso si un banner del runtime o recordatorio del sistema lo solicita.

6. Revisores opcionales (nunca bloqueantes)

Para cada entrada en profile.review.optional_reviewers, ejecutar una revisión justo después de que se abra el PR, saltando cualquier entrada cuyo enabled sea false. Una entrada deshabilitada no lanza nada: ningún proceso, ningún subagente, ningún archivo de informe, y la evidencia registra ": deshabilitado". Nunca se registra como pasada, omitida por fallo o limpia. Un informe que una cabeza anterior dejó bajo la misma etiqueta se nombra donde está, nunca se elimina, por lo que no puede leerse como el estado del asiento deshabilitado. Omisión significa habilitado. Pasar el valor de la entrada al lanzador como --enabled true o --enabled false, el literal en minúsculas al que su clave enabled se renderiza, con una entrada que omita la clave pasando --enabled true. El lanzador se niega a lanzar y no escribe ningún informe para el valor falso, por lo que la omisión se aplica en lugar de confiarse al llamante. scripts/batched-diff-review.sh es un lanzador genérico: construir --agent-cmd desde la entrada y pasar --base origin/<rama de integración>. Agrupa el diff por un presupuesto de líneas con un plano entre archivos, ejecuta el revisor en un directorio vacío sin acceso al repositorio y escribe un informe que termina en PASS, FAIL o INCOMPLETE. Cada lote debe devolver exactamente un veredicto PASS o FAIL por archivo que se le dio; un veredicto faltante, extra o no analizable hace que el lote sea INCOMPLETO. El prompt del lote llega al agente en stdin (para codex, terminar el comando con -) y como {prompt_file}; nunca poner el prompt o el diff en argv.

• Un intento. En caso de INCOMPLETO (límite de tasa, tiempo de espera, credencial faltante), registrar ": omitido" y proceder; nunca solucionarlo y nunca retener una fusión o despliegue por ello.
• Cuando una revisión se completa, verificar cada hallazgo contra el código antes de actuar: resolver los Críticos y Altos antes de fusionar; resolver los hallazgos Medios válidos o documentar por qué no; resolver los hallazgos Bajos cuando sean claramente útiles; rechazar falsos positivos explícitamente.
• Después de cambios de código, volver a ejecutar las pruebas relevantes y el revisor opcional en la nueva cabeza, solo sobre sus entradas habilitadas.

7. Revisión de registro (obligatoria)

Ejecutar la puerta en references/code-review.md una vez que el PR esté abierto: profile.review.reviewer revisa la cabeza en un árbol de trabajo desechable, luego profile.review.adjudicator, un agente limpio y neutral, verifica cada hallazgo contra el código. Ambos agentes son limpios, neutrales e independientes del autor; un agente que revisa y adjudica sus propios hallazgos no es válido. Si profile.review.shadow_adjudicators está configurado, ejecutar cada uno como describe references/code-review.md; registra solo acuerdo y nunca bloquea la fusión. Una entrada allí cuyo enabled sea false se omite de la misma manera que un revisor opcional: ningún subagente, sin registro de archivo, y la evidencia registra ": deshabilitado".

Puerta de revisión de registro

1. Revisor. …

[Nota: El contenido original fue truncado en la solicitud. El marcado anterior traduce fielmente el texto proporcionado hasta donde fue posible, siguiendo todas las reglas de formato y preservando los elementos técnicos no traducibles.]