Work Items y estados
Feature frente a Task, los estados del ciclo, sus ramas y el límite de un solo Work Item en in_progress.
Feature o Task
Todo trabajo nace como Work Item con un identificador y un tipo. El tipo no es una etiqueta cosmética: decide la planificación que se genera y si la integración con GitHub Issues abre issue y rama.
| Tipo | Planificación | Cuándo usarlo |
|---|---|---|
| Feature | requirements.md, design.md y tasks.md | El trabajo necesita especificarse, hay varias decisiones de diseño o cambia el comportamiento o la arquitectura. |
| Task | plan.md | Documentación, contratos o un cambio pequeño y localizado, sin cambio de comportamiento ni de arquitectura. |
El ciclo de estados
Features y Tasks comparten el mismo ciclo. Todo Work Item comienza en pending, pasa por la planificación y la aprobación, se implementa, se revisa y termina en done. Cada estado describe una etapa real del trabajo, no una etiqueta decorativa.
| Estado | Significado | Carácter |
|---|---|---|
| pending | Work Item creado, pendiente de planificación. | Ciclo |
| ready | Planificación terminada, esperando aprobación humana. | Ciclo |
| in_progress | Implementación en curso. Solo puede haber uno a la vez. | Ciclo |
| review | Implementación finalizada, pendiente de revisión. | Ciclo |
| done | Completado y aprobado; estado terminal. | Terminal |
El paso de ready a in_progress es la aprobación humana. El paso de in_progress a review lo registra el Implementer al terminar, y el de review a done requiere el veredicto del Reviewer. Ningún atajo elimina esos puntos.
Las ramas del ciclo
Dos estados quedan fuera del recorrido lineal. No son atajos ni estados de éxito: describen trabajo detenido o una revisión que exige correcciones.
| Estado | Significado |
|---|---|
| blocked | El trabajo no puede continuar. |
| changes_requested | La revisión rechazó la implementación y pide cambios. |
- blocked se alcanza desde cualquier punto del ciclo cuando el trabajo no puede continuar; solo se sale con una causa resuelta.
- changes_requested lo produce un rechazo del Reviewer. El Work Item vuelve a in_progress con las correcciones solicitadas.
- done es terminal: no se sale de él por una transición estándar. Una transición no estándar exige
--forcey una orden explícita.
Dónde vive el estado
El estado no vive en la conversación ni en la memoria del agente. Se registra en dos archivos con responsabilidades distintas y complementarias.
| Archivo | Qué registra | Para qué sirve |
|---|---|---|
meta.json | Tipo, estado, base_commit y last_review_commit de cada Work Item. | Registro duradero y diagnóstico del conjunto de Work Items. |
current.md | Estado, bitácora y próximo paso de la sesión activa. | Retomar el trabajo exactamente donde quedó si la sesión se interrumpe. |
El límite de un solo in_progress es duro. Lo aplican rei status set al intentar activar otro Work Item, también con --force, y lo comprueban rei check, rei doctor y rei items status. Antes de iniciar otro, hay que cerrar, bloquear o revisar el activo.
Siguiente paso
Con el vocabulario claro, el siguiente paso es entender la puerta que separa ready de in_progress o recorrer el ciclo completo con un Work Item real.
La firma humana libera la hoja. El silencio no aprueba.