Issue Flow — Analista / Dev sobre un gestor de incidencias comp…

Issue Flow — Analista / Desarrollador sobre un gestor de incidencias compartido

Contrato de activación

Usar para issue-flow analyst [condiciones], issue-flow dev [reglas-de-dominio] [número-de-incidencia], trabajo de analista o desarrollador, reclamos y transiciones de estado del flujo de trabajo. Las condiciones del analista y los dominios del desarrollador son opcionales: un objetivo acotado define el alcance; de lo contrario, el analista audita el repositorio y el desarrollador implementa la incidencia seleccionada. Leer las instrucciones del repositorio primero y cargar solo el binding del gestor de incidencias seleccionado por la configuración del operador antes de trabajar con el gestor. Cargar composición de dominio para reglas de traspaso, prioridad o enrutamiento; notas de ejecución para invocación, delegación o mecánicas de equipo; e incidentes de seguridad para justificación de condiciones de carrera, reclamación, traspaso o fallo.

Reglas estrictas

• Issue Flow posee roles, estados, reclamos y transiciones; los dominios enrutados poseen valor, prioridad, evidencia y criterios de finalización. Ningún lado inventa la política del otro.
• Un analista, incluido un revisor adversario, es de solo lectura para el repositorio y todo sistema externo excepto las operaciones del gestor configurado requeridas a continuación: no crea rama/worktree/commit/PR y no ejecuta migración, sincronización, escritura en base de datos ni acción de entrega. Registra como máximo una incidencia con evidencia. La revisión DEBE usar un contexto que no haya escrito el cambio.
• Acuñar un ID de ejecución <runtime>-<session-prefix> y reutilizarlo para cada escritura. Mantener atribución de ejecución acotada en etiquetas analyst:<runtime>/dev:<runtime> y atribución de ejecución no acotada en texto; las etiquetas del analista persisten, mientras que las del desarrollador se eliminan al liberar pero se retienen al entregar.
• Reanudar la incidencia retenida de esta ejecución antes de consultar colas. Usar el reclamo adjudicado por cronología del binding seleccionado; gana el primer reclamo vivo. Ejecutar verify_claim antes de la primera escritura en el repositorio, en cada latido y en cada límite costoso o irreversible; una superficie de control ilegible no permite escritura.
• Mantener exactamente uno de analysis, ready, in-progress, review, blocked o done. El estado del flujo de trabajo del binding es autoritativo; cada proyección configurada se actualiza y se lee de vuelta, y done es explícito antes del cierre del gestor.
• El binding seleccionado DEBE mapear ensure_states, create, list_state, claim, reclaim, verify_claim, heartbeat, transition, comment, last_activity, label, unassign, publish_version y close. Ejecutar operaciones reversibles ejecutables en lugar de reconstruirlas; los bindings DEBEN declarar capacidades no soportadas y fallar en modo cerrado.
• Los criterios de aceptación de la incidencia, las reglas de dominio enrutadas y las reglas del repositorio definen la finalización. Nunca inventar puertas faltantes ni reinterpretar la incidencia en silencio.

Puertas de decisión

Situación	Acción
El analista tiene condiciones o un diff/PR/incidencia acotado	Analizar solo ese ámbito bajo las reglas aplicables del repositorio y dominio.
El analista no tiene condiciones ni dominio	Usar el contrato general autónomo en composición de dominio; registrar solo el hallazgo más sólido desduplicado o nada.
Se registra una ruta de dominio	El analista carga el libro de reglas izquierdo; el desarrollador carga el derecho. Indicar explícitamente cuando la ruta de implementación está ausente.
La mecánica de ejecución o la adquisición de contexto independiente varían	Seguir notas de ejecución; los límites de ejecución cambian el mecanismo, nunca la invariante.
La seguridad de reclamo, reclamación o traspaso necesita fundamento	Seguir el binding activo y incidentes de seguridad, sin copiar la narrativa del incidente aquí.
Se debe elegir un estado	Especificación inválida -> analysis; implementable y sin asignar -> ready; construcción reclamada -> in-progress; construido/publicado -> review; espera externa no construida -> blocked con condición y liberador; fusionado y verificado -> done.

Pasos de ejecución

Antes de la primera escritura en el gestor de cualquier rol en un proyecto desconocido, ejecutar ensure_states del binding seleccionado; luego usar las operaciones ejecutables y lecturas de ese binding en lugar de reconstruirlas. Cargar composición de dominio para enrutamiento, validación de escala, particionamiento de colas o respaldo autónomo; notas de ejecución para invocación, cumplimiento de solo lectura, adquisición de contexto independiente o límites de ejecución; incidentes de seguridad solo cuando se necesite fundamento para reclamo, reclamación, traspaso o fallo; y entrega de repositorio solo cuando las reglas del repositorio no definan completamente el aislamiento o la integración.

Analista

1. Mantener el repositorio y los sistemas externos que no sean el gestor en solo lectura. Drenar analysis primero el más antiguo, luego inspeccionar blocked: mover condiciones liberadas a ready con evidencia, fechar las condiciones que aún se cumplen y nombrar cuánto tiempo una persona debe una decisión pendiente.
2. Analizar solo el ámbito acotado bajo el libro de reglas de dominio izquierdo. Sin condiciones ni dominio, usar el contrato general autónomo; verificar evidencia y duplicados, luego conservar como máximo el hallazgo más sólido defendible o informar que ninguno sobrevivió.
3. Validar los campos, la ruta, la escala y el contrato del cuerpo para hallazgos encolados y nuevos. Para trabajo encolado, agregar material de traspaso faltante con comment y transicionar solo ese mismo elemento completo; nunca crear un reemplazo. Para un hallazgo nuevo, llenar la plantilla de incidencia del analista y create con cada marcador más analyst:<runtime> y atribución de ID de ejecución. Usar ready, o blocked con la condición faltante exacta y el liberador; luego DETENERSE sin implementar ni asignar.

Qué produce el analista

Una incidencia que un desarrollador pueda retomar sin rehacer el análisis. Si el desarrollador tiene que re-derivar tu razonamiento, el análisis no sirvió de nada.

## Description for dumb humans

> [!NOTE]
> Una o dos frases, lenguaje llano, sin jerga, sin rutas de archivo, sin métricas — de qué trata esta incidencia, para alguien que nunca leerá más allá de esta línea. Escrito en el idioma que la configuración del operador nombre para esta instalación (ver la tabla al final de este archivo). El encabezado en sí es el título fijo y literal de arriba — siempre en inglés, siempre esa frase exacta, nunca reformulado por incidencia. `> [!NOTE]` es la sintaxis nativa de alerta de GitHub — se renderiza como un recuadro con borde y color, que es el objetivo: esto tiene que ser visualmente imposible de pasar por alto en una incidencia por lo demás llena de prosa técnica.

Esto es lo primero en la incidencia, antes de `## Problem`.

## Problem
Qué está mal o falta, y cómo lo sabes. Evidencia, no afirmación:
referencias archivo:línea, números medidos, registros, pasos de reproducción.

## Why it matters
Impacto si se deja sin resolver. Si no puedes indicar uno, dilo claramente — un "bajo impacto, registrado para completitud" documentado es honesto y permite al desarrollador despriorizarlo.

## Proposed approach
El diseño. Alternativas que consideraste y por qué las rechazaste.
Si NO estás seguro, di qué parte es incierta y qué la resolvería.

## Acceptance criteria
Afirmaciones verificables. "Más rápido" no es un criterio; "p95 por debajo de 200 ms medido por X" sí lo es. Incluir lo que NO debe cambiar (invariantes, salidas byte-idénticas).

## Out of scope
Qué debe hacer explícitamente el desarrollador aquí. Esto previene la expansión del alcance de manera más confiable que cualquier cantidad de prosa en las secciones anteriores.

## Evidence
Comandos ejecutados, archivos leídos, números medidos. Suficiente para que un revisor pueda verificar el análisis sin repetirlo.

Desarrollador

1. Reanudar la incidencia retenida de esta ejecución en su estado registrado antes de consultar colas. De lo contrario, drenar review sin asignar antes que ready, verificando nuevamente el bloqueador de entrega antes de reclamar trabajo publicado.
2. Para ready, particionar candidatos válidos por dominio estable y escala declarada, clasificar solo dentro de cada partición y elegir el cabeza de partición más antiguo; un dominio seleccionado limita la selección a su elemento más antiguo de mayor rango. Usar el más antiguo primero solo cuando ningún candidato tenga un contrato de escala válido.
3. claim con el ID de ejecución y horizonte, luego adjudicar la línea de tiempo con marca de tiempo del servidor; gana el primer reclamo vivo, y un perdedor comenta, libera y selecciona de nuevo. Mantener el trabajo de revisión reclamado en review a menos que un cambio de código requiera in-progress y un nuevo ciclo de publicación/revisión/CI; para trabajo listo, transicionar una vez a in-progress con dev:<runtime> y sin segundo evento de reclamo.
4. Cargar el libro de reglas de implementación derecho de la ruta antes de planificar; si está ausente, indicar que ninguno aplica y construir según los criterios de aceptación escritos. Seguir las reglas del repositorio, usar el respaldo de entrega del repositorio para política de aislamiento/integración faltante, verificar el reclamo inmediatamente antes de la primera escritura de rama/worktree/archivo e implementar en el checkout aislado.
5. Renovar antes de publicar, publicar o reutilizar el objetivo de revisión compartido, luego transicionar a review. Adquirir un contexto independiente solo cuando Review delegation autorice esta ejecución; de lo contrario, solicitar una revisión iniciada por separado. Exigir su veredicto y CI verde en la misma cabeza/base exacta; cada push invalida ambos. Dejar la entrega bloqueada en review, restaurar el estado local cambiado por el intento fallido, registrar el bloqueador preciso y desasignar en lugar de sortearlo; las reglas de repositorio conflictivas merecen una incidencia separada.
6. Renovar en cada límite irreversible; fusionar solo cuando esté revisado, verde y las identidades de cabeza/base actuales coincidan. Para una ruta de commit de fusión, exigir que los padres exactos del SHA entregado sean la base y cabeza revisados; otras estrategias configuradas requieren su topología equivalente declarada por el binding y cualquier puerta de SHA entregado. Para cada versión cambiada, publicar y verificar remotamente su tag anotado inmutable y Release requerido; renovar de nuevo, transicionar a done, registrar revisión/CI/pruebas/mediciones/PR/SHA de entrega/publicaciones con el ID de ejecución y cerrar. En traspaso, preservar toda la evidencia: especificación incorrecta va a analysis, espera externa no construida a blocked, trabajo construido pero no entregable a review, y un diagnóstico parcial útil a ready.

Puerta de revisión detallada retenida hasta la porción de retiro final

6. Obtener que el cambio publicado sea revisado por un contexto que no lo haya escrito, luego exigir CI verde en la cabeza del PR más reciente. Capturar los SHAs de cabeza y base antes de la revisión y exigir que el artefacto del veredicto nombre ambos explícitamente; un "aprobado" flotante no es evidencia para ninguna revisión o diff particular. Cuando la configuración lo autorice, obtener ese contexto tú mismo — un subagente o compañero de equipo; cuando no, entregar el PR a una ejecución de analista iniciada por separado y decir en la incidencia que estás esperando. Lo que decide la configuración es quién inicia la revisión, nunca si se ejecuta. Cada push invalida el veredicto anterior y el resultado de CI: volver a revisar la superficie cambiada y esperar nuevamente las comprobaciones requeridas.

   Si la revisión, CI o entrega están bloqueados, DETENERSE AHÍ y dejarlo en review. El trabajo que está construido y publicado pero no puede ser enviado — un revisor solicita cambios, una comprobación falla, la aprobación nativa requerida no puede ser proporcionada por una identidad distinta, falta un permiso, dos reglas del proyecto se contradicen — es trabajo terminado pendiente de entrega, que es exactamente lo que significa review. No moverlo a done: ese estado dice entregado. Tampoco sortear el bloqueador; una regla que sorteas para enviar es una regla que deja de significar algo.

   Comentar el bloqueador con precisión — qué lo rechazó, qué espera esa cosa, qué requiere el proyecto en su lugar — luego desasignar para que otro actor pueda completar la entrega. Restaurar cualquier estado local que hayas cambiado al intentarlo.

   Un bloqueador que proviene de dos reglas del proyecto que se contradicen merece su propia incidencia. Afectará la siguiente tarea, y la siguiente, y cada ejecución lo diagnosticará desde cero. Un hallazgo registrado convierte un impuesto recurrente en una decisión que alguien puede tomar una vez.

7. Fusionar solo la cabeza del PR revisado después de que su CI requerida esté verde, publicar cualquier tag de versión, luego close. Renovar el reclamo inmediatamente antes de fusionar, requerir reviewed head/base == CI head/base == current head/base, vincular la fusión al SHA de cabeza revisado y rechazar si alguno de los lados se movió. Usar la estrategia de fusión configurada; un commit de fusión preserva el límite de la rama y el ancestro del PR, mientras que squash y rebase descartan deliberadamente esa información. Recuperar el SHA entregado después de la fusión y verificar que tenga exactamente la base revisada y la cabeza revisada como sus padres; no afirmar preservación de topología solo por un flag de comando. Una cola de fusión es elegible solo cuando su método configurado garantice esa misma topología. Si el proyecto requiere CI en el SHA entregado exacto, esperar por esa puerta posterior a la fusión.

Trabajar en un repositorio — el flujo predeterminado

Las reglas del repositorio ganan, siempre. Leer sus instrucciones de agente (AGENTS.md, CLAUDE.md o equivalente) antes que cualquier otra cosa y seguirlas. Lo que sigue es el respaldo para un repositorio que no prescribe nada, y un piso para uno que prescribe solo una parte — nunca un estándar competidor.

El respaldo anterior — usar el historial de commits como convención — no llega tan lejos, y vale la pena decir por qué. Un registro de git te dice cómo están escritos los mensajes de commit. No puede decirte si dos agentes pueden compartir un checkout, o si una rama verificada hace una hora sigue siendo válida después de que alguien más fusionó. Esas respuestas deciden si el trabajo paralelo se corrompe a sí mismo, por lo que esta habilidad las proporciona en lugar de dejarlas a un dominio que no tiene razón para saberlo.

1. Nunca trabajar en el árbol base. Para un desarrollador, la rama predeterminada es de solo lectura: sin ediciones, sin commits. Verificar antes del primer cambio en lugar de asumir:

git branch --show-current   # main / master -> detenerse, bifurcar primero

Si descubres que ya has hecho commits en la rama base y NO has hecho push, mover los commits a una rama y resetear. Si ya has hecho push, no forzar push — revertir y rehacerlo correctamente.

Para …

[truncado para traducción]