PRD Lifecycle

¿Qué hace PRD Lifecycle?

Unifica las capacidades de creación, refinamiento, revisión y planificación de ejecución de PRD en una sola entrada, manteniendo los límites de autorización y las puertas de confirmación propias de cada fase.

Enrutamiento de modos

Primero evalúa los materiales que posee el usuario y el resultado esperado, entrando solo al modo necesario, sin forzar un recorrido completo desde el principio.

Modo	Entrada típica	Producto principal	Límite clave
create (crear)	Idea funcional + repositorio existente	Informe de estado, línea base confirmada, PRD versionado	Primero recopila evidencia, confirma paso a paso; no genera PRD hasta aprobar la línea base
refine (refinar)	Borrador de PRD/requisitos	Revisión por partes, historial de versiones, opcional .docx	Cada paso se revisa primero; solo escribe y versiona tras confirmación
review (revisar)	PRD específico + línea base/repositorio opcional	Problemas clasificados, evidencia, recomendaciones	Solo revisa; no modifica el documento ni implementa código
execute (ejecutar)	PRD aprobado + repositorio existente	Auditoría de preparación, documento de ejecución, matriz de trazabilidad, prompt de control	Solo planifica; no modifica el PRD ni implementa código

Reglas de enrutamiento:

• Si solo hay una idea y se desea formar un PRD combinándola con el proyecto existente: usa create.
• Si ya hay un borrador cuyo objetivo es completar, revisar, refinar o producir una versión final: usa refine.
• Si el objetivo es encontrar contradicciones, riesgos, omisiones o elementos no verificables, sin pedir modificaciones: usa review.
• Si hay una versión aprobada explícita y el objetivo es que Codex la desarrolle por fases: usa execute.
• Cuando el usuario solicite un tratamiento integral, comienza desde la fase más temprana aplicable; en cada puerta de confirmación detente y espera autorización, sin avanzar automáticamente.
• Si "revisar" podría significar tanto revisar como modificar, prioriza el modo de solo lectura review e indica que los resultados de la revisión pueden pasar a refine si el usuario lo autoriza.
• Si el usuario solo desea evaluar e implementar cambios locales de código, UI, interacción, refactorización o arquitectura en el repositorio existente, usa repo-grounded-change; no fuerces escribir primero un PRD.

Restricciones compartidas

Orden de autoridad

A menos que el usuario especifique lo contrario, procesa los conflictos en el siguiente orden:

1. Instrucción explícita actual del usuario.
2. Decisiones explícitamente confirmadas en la tarea actual.
3. Línea base de requisitos y PRD aprobados especificados.
4. Comportamiento existente demostrado por el código y las pruebas actuales.
5. Documentación actual del producto.
6. Borradores históricos, registros de revisión y recomendaciones.

El PRD objetivo no es correcto por defecto; cuando surja un conflicto, muéstralo junto con su impacto y la decisión necesaria, sin elegir un lado en silencio. El código sirve para probar el estado actual, pero no puede negar los nuevos requisitos ya aprobados.

Etiquetas de hecho y sugerencia

Úsalas cuando la conclusión pueda ser ambigua: confirmado, hecho de código, hecho de documentación, suposición de producto, sugerencia técnica, pendiente de confirmación, no implementado en esta iteración.

Límites de autorización

• No inventes reglas de negocio, estados, umbrales, permisos, prioridades, dependencias, integraciones externas ni criterios de aceptación.
• No consideres la finalización de una fase, la aprobación de una revisión ni la generación de un plan como autorización para implementar.
• No modifiques código de negocio, no hagas commit, push, deploy ni invoques sistemas de producción externos.
• Verifica el árbol de trabajo y protege las modificaciones existentes del usuario; si no puedes evitar una superposición de forma segura, detente y explica la zona de conflicto.
• Ejecuta solo el modo solicitado por el usuario. Para pasar al siguiente modo debe haber una petición o confirmación explícita.

create: Creación de PRD tras investigación del repositorio

1. Lee project-discovery.md, examina el repositorio, la documentación del producto, las pruebas y el árbol de trabajo, y genera un informe del estado actual. A menos que el usuario solicite explícitamente fusionar el flujo, detente y espera la confirmación del estado.
2. Lee clarification-rounds.md y planifica los temas según las brechas de evidencia. Cada ronda cubre solo un tema, presentando 1–3 preguntas de opción múltiple mutuamente excluyentes; recomienda una opción al inicio y explica su impacto.
3. Tras la respuesta del usuario, primero resume los elementos confirmados, los no confirmados, los conflictos y el impacto descendente; luego espera la confirmación de ese resumen de la ronda. No avances al siguiente tema sin confirmación.
4. Una vez confirmados todos los temas relevantes, lee baseline-and-prd.md, genera la línea base de requisitos confirmados y detente.
5. Solo después de que el usuario apruebe explícitamente la línea base y solicite generar el PRD, crea el PRD versionado; busca versiones existentes e incrementa, sin sobrescribir en silencio.

Criterio de finalización: El PRD es coherente con las decisiones confirmadas, el alcance y los no-objetivos están claros, los requisitos y la aceptación son trazables, el impacto en el repositorio está respaldado por evidencia, y los asuntos pendientes no se disfrazan como requisitos finales.

refine: Refinamiento paso a paso y revisión versionada

1. Lee el texto original completo, preserva el significado original y establece una línea de trabajo base. Si es necesario crear un nuevo documento de trabajo en Markdown, usa scripts/prd_doc.py init para establecer v1.0 y el esqueleto de secciones.
2. Lee la subsección del paso actual en refinement-steps.md. El esqueleto predeterminado es:
   • Clarificación de requisitos e historias de usuario;
   • Propuesta de funcionalidad;
   • Condiciones límite;
   • Criterios de aceptación.
3. Realiza solo el paso actual a la vez. Primero presenta el contenido a revisar en el diálogo, sin escribir en el archivo prematuramente.
4. Cuando el usuario solicite modificaciones o adiciones, permanece en el paso actual sin versionar. Solo después de que el usuario confirme explícitamente, escribe en el documento y realiza un versionado menor (minor) según versioning.md y un registro de revisión.
5. Si se necesitan métricas, planificación de dependencias, rollback de riesgos, cumplimiento normativo o relleno de comentarios de revisión, se pueden insertar pasos extendidos; igualmente se aplica la puerta de "producción → revisión → confirmación → escritura → versionado".
6. Una vez confirmados todos los pasos, fusiona el documento completo y realiza un versionado mayor (major). Si el usuario solicita .docx, usa scripts/prd_doc.py export y realiza la validación de formato con las herramientas de documentación disponibles.

Cada paso no solo debe completar, sino también señalar elementos vagos, contradictorios, no verificables y escenarios fácilmente pasados por alto en el texto original. Las historias de usuario, funcionalidades, límites y criterios de aceptación deben ser trazables entre sí; los elementos de aceptación deben incluir condiciones explícitas y resultados observables.

Completar el refinamiento no equivale a que el PRD esté aprobado comercialmente, ni entra automáticamente en review o execute.

review: Revisión adversarial basada en evidencia

1. Lee review-protocol.md, confirma la versión objetivo, el alcance de la revisión, las fuentes autoritativas, la evidencia del repositorio y los materiales faltantes. Lee el PRD objetivo completo.
2. Extrae el alcance, tipo, estado, umbral, permisos, datos, tiempo, prioridades e invariantes de aceptación.
3. Lee finding-taxonomy.md y revisa respectivamente: regresión de línea base, consistencia interna, ciclo de vida, historial de datos, idempotencia de interfaz, auditoría de permisos, límites de prototipo, NFR, ejecutabilidad y trazabilidad FR/AC.
4. Después de deduplicar, conserva solo los problemas que tengan evidencia, consecuencia y posibilidad de corrección. No crees hallazgos solo para parecer exhaustivo.
5. Lee review-report.md, emite Pass, Pass with changes, Blocked o Limited review, y presenta los hallazgos por gravedad, con evidencia, impacto y la recomendación de corrección mínima.

La revisión es de solo lectura por defecto. Incluso si se encuentran problemas evidentes, no modifiques directamente el PRD; después de que el usuario autorice la revisión, pasa a refine.

execute: Conversión a documento de ejecución de desarrollo para Codex

El requisito previo es que exista un PRD aprobado con una versión identificable. Completar el refinamiento o superar la revisión no equivale a aprobación.

1. Lee readiness-audit.md, verifica la versión del PRD, la línea base confirmada, el alcance de la entrega objetivo, los asuntos pendientes, el repositorio actual y las pruebas, generando una tabla de brechas y una conclusión de preparación.
2. Si el comportamiento del producto no se puede determinar de forma única, hay conflictos de autoridad, los criterios de aceptación no son observables, o se necesitan dependencias/integraciones/migraciones no autorizadas, la conclusión es BLOCKED y se detiene, sin ocultar los problemas en suposiciones técnicas.
3. Lee execution-document.md, define el límite arquitectónico mínimo que satisface el PRD, incluyendo propiedad, estado, datos, interfaz, persistencia, reloj, degradación y protección de sistemas existentes.
4. Comenzando con la Fase 0 de solo lectura, crea fases ordenadas por dependencias, independientemente revisables. Cada fase especifica FR/AC, alcance de archivos, elementos prohibidos, pruebas, evidencia de aceptación, puertas de calidad y puertas de parada.
5. Lee traceability-and-gates.md, mapea cada FR/AC dentro del alcance a fases, áreas de código, pruebas y evidencia, identificando requisitos huérfanos y trabajo no autorizado.
6. Lee codex-control-prompt.md, genera un prompt de control general y prompts por fase. El prompt debe conservar la versión, el orden de autoridad, las pruebas reales, la protección de cambios del usuario y la autorización por fases.

Criterio de finalización: Otra instancia de Codex puede comenzar desde una auditoría de solo lectura, ejecutar solo una fase aprobada, verificar con comandos reales, informar los resultados de trazabilidad y detenerse; el documento define claramente suposiciones, exclusiones, bloqueadores, elementos pospuestos y comportamientos protegidos.

Puertas de enlace entre fases

• create → refine: Solo se entra si el usuario considera que el PRD generado aún necesita completarse o revisarse.
• create/refine → review: Debe ser solicitado explícitamente por el usuario; la revisión no modifica automáticamente.
• review → refine: Se entra después de que el usuario autorice explícitamente el tratamiento de hallazgos específicos, manteniendo el ID del hallazgo y el mapeo de revisión.
• create/refine/review → execute: Debe especificarse explícitamente una versión de PRD "aprobada" y el alcance de la entrega objetivo.
• execute → implementación: El documento de ejecución solo proporciona el plan de control; la implementación real debe ser autorizada por el usuario en una tarea posterior.

Aprendizaje por feedback

Al comenzar el flujo de trabajo, lee feedback-learning.md y learned-guidance.md. El feedback se aplica primero a la tarea actual; solo se permite la persistencia si el usuario solicita explícitamente recordar y confirma la regla específica y su alcance. Las reglas aprendidas no pueden anular la instrucción actual, las puertas de fase, la verificación de hechos, la gestión de versiones ni los límites de autorización.