Refinar Historia de Usuario

¿Qué hace Refinar Historia de Usuario?

Refina una Historia de Usuario mediante examen socrático: entrevista al PO en rondas estructuradas hasta que la frontera de decisiones esté vacía, luego sintetiza. Una sesión efectiva transforma una discusión de refinamiento de 40 minutos en una confirmación de 10 minutos, porque el equipo llega a la planificación con decisiones registradas y brechas identificadas explícitamente.

La historia pertenece al PO. Tú auditas, propones e indagas; cada edición preserva el objetivo de negocio original, y cualquier reescritura que requeriría decisiones de alcance se convierte en una pregunta, no en una elección unilateral. El riesgo de invención es agudo aquí: una HU existente a menudo parece "casi lista" y la tentación de completarla en silencio es fuerte. Una HU con brechas visibles es mucho más valiosa para el refinamiento que una historia "completa" con reglas que el PO nunca escribió.

HU: $ARGUMENTS

Antes de comenzar

Lee docs/agents/refinement.md en el espacio de trabajo: define el modo de operación (con o sin código), idioma (en-US o pt-BR, por defecto en-US), slugs y rutas de publicación. Si falta, pide al usuario que ejecute /configure-refinement y detente. Todo el diálogo de examen, preguntas y el artefacto sintetizado siguen el idioma configurado del espacio de trabajo.

Pasos

1. Cargar. Lee la HU (ruta de archivo, ID del tracker o texto pegado), CONTEXT.md, ADRs de dominio e invoca la herramienta Skill para requirements-rigor. Si .scratch/<slug>/ ya existe para esta HU, inspecciona su contenido: una sesión anterior puede haber resuelto preguntas, las cuales no debes repetir. El slug sigue las convenciones en docs/agents/refinement.md. Si docs/adr/ o .scratch/ están ausentes, procede sin advertencia. Completado cuando: puedes clasificar la HU en una línea: ANALIZABLE (tiene narrativa y algunos criterios, aunque sean defectuosos), ESQUELETO (solo título, o narrativa sin criterios) o NO ES UNA HU (épica disfrazada, tarea técnica, requisito no funcional independiente).

2. Triaje. NO ES UNA HU: indica qué tipo de artefacto es realmente, proporciona una justificación de 2 a 3 líneas y recomienda el manejo apropiado: épica disfrazada, descomponer con /requirements-discovery; tarea técnica, reclasificar como tarea; requisito no funcional independiente, mover a la lista de requisitos no funcionales. Si el elemento vive en el espacio de trabajo, añade Status: not a US (o Status: não é US) y la justificación debajo del título para dejar un rastro. Detente aquí. ESQUELETO: procede, y la primera ronda de examen pide los escenarios faltantes en lugar de inventarlos. Completado cuando: la clasificación está expresada en una sola línea y, en el caso de NO ES UNA HU, también se proporcionan la justificación y el manejo.

3. Auditar en silencio. Aplica las reglas de requirements-rigor a la narrativa y criterios: INVEST, Gherkin, antipatrones (lee ANTI-PATTERNS.md por separado), términos que siempre disparan preguntas. Cada hallazgo se convierte en una pregunta candidata o una corrección que preserva el comportamiento descrito exactamente: convertir prosa a Gherkin, mover DoD fuera de los criterios, mover tareas de implementación a notas. Completado cuando: cada criterio tiene un destino (conservar, convertir, mover, preguntar) y cada término ambiguo tiene una pregunta candidata.

4. Buscar hechos antes de preguntar. Los hechos son tu responsabilidad, nunca del PO. Para cada pregunta candidata, busca en fuentes del espacio de trabajo: glosario, historias anteriores en .scratch/, documentos adjuntos por el PO. En modo con código, despacha un subagente para buscar en la base de código lo que la HU afirma o asume: ¿existe la regla? ¿está implementado el límite? ¿funciona la integración? Un hecho encontrado se convierte en una respuesta recomendada citando la fuente. En modo sin código, la búsqueda se limita a archivos del espacio de trabajo sin subagentes; si no se encuentra nada, indícalo en una sola línea al inicio de la ronda 1. Completado cuando: cada pregunta candidata está marcada como respondida por una fuente (con cita) o abierta para el PO.

5. Examinar. Invoca la herramienta Skill para socratic-examination y sigue su disciplina: rondas, frontera, respuestas recomendadas con citas o "sin recomendación", hechos tuyos y decisiones del PO, glosario actualizado inmediatamente. La Ronda 1 abre con triaje de una línea, marca las preguntas que bloquean el veredicto y cierra con notas sobre criterios movidos sin preguntas y preguntas redirigidas al equipo de ingeniería. Las preguntas arquitectónicas no entran en rondas con el PO: redirígelas directamente a preguntas abiertas para el equipo de ingeniería. Las preguntas que el PO no puede responder reciben [TO CONFIRM: whom] (o [A CONFIRMAR: quem]) y abandonan la frontera. Completado cuando: la frontera está vacía, o el PO solicita cerrar con la información actual.

6. Sintetizar. Escribe la HU refinada siguiendo TEMPLATE.md, con las brechas restantes visibles como marcadores. Ejecuta la autoauditoría de Gherkin. Entrega el veredicto: LISTA, REFINAR con números de pregunta que la desbloquean, o BLOQUEADA con justificación. Si [DECOMPOSE] está presente, incluye la propuesta de descomposición: narrativa para cada parte y mapeo de criterios originales. Completado cuando: el archivo existe en la ruta definida por docs/agents/refinement.md, con Status: coincidiendo con el veredicto y el descargo de responsabilidad final presente.

7. Enrutar elementos abiertos. Para cada destinatario fuera de la sesión con [TO CONFIRM], escribe un cuestionario siguiendo QUESTIONNAIRE.md en requirements-rigor, junto con la HU refinada, y enlaza el archivo desde la sección de preguntas abiertas. Completado cuando: no queda ningún [TO CONFIRM] sin un destinatario o cuestionario.

8. Reportar. Informa al usuario de manera concisa: veredicto, dónde se publicó la HU, qué preguntas la desbloquean y los cuestionarios generados.

Ejemplo de ronda

Para la HU "Como usuario, quiero exportar informes a PDF para facilitar el compartir. CA1: el botón de exportación debe funcionar correctamente. CA2: crear un servicio de generación de PDF en el backend. CA3: el PDF debe abrirse rápido. CA4: código revisado y pruebas pasando.", en un espacio de trabajo sin código cuyo glosario enumera analista de operaciones y gestor de cuentas como consumidores de informes, la primera ronda se ve así:

❓ P1. ¿Quién exporta? (bloqueante) La narrativa indica "usuario". El glosario enumera analista de operaciones y gestor de cuentas como roles que consumen informes. ¿Qué rol exporta, o ambos? Recomendación: analista de operaciones [INFERENCIA: rol asociado con "informes operativos" en el glosario]. Sin esto, los permisos permanecen indefinidos y la narrativa falla INVEST.

❓ P2. ¿Qué significa "abrirse rápido"? (bloqueante) CA3 no es comprobable y admite dos lecturas: tiempo entre disparar la exportación y que la descarga comience, o tiempo para que el archivo se abra en un lector. ¿Cuál es la intención, y cuál es el tiempo máximo en segundos? Recomendación: sin recomendación: el texto fuente no proporciona base para interpretación ni números de SLA. Si no existe expectativa, registra [TO CONFIRM: PO] y procede.

❓ P3. Casos límite La fuente insinúa informes vacíos e informes de alto volumen [INFERENCIA: los informes varían en volumen]. ¿Cuáles son relevantes para esta entrega? Recomendación: incluir ambos como escenarios [INFERENCIA: se derivan del texto fuente]. El comportamiento específico para cada uno es tu decisión: sin recomendación. El volumen máximo depende de P2.

CA2 y CA4 no disparan preguntas: CA2 es una tarea de implementación cuyo comportamiento habilitado está cubierto por CA1, moviendo a notas; CA4 es Definición de Hecho del equipo y se elimina de los criterios. Ambos aparecen en la sección de auditoría del artefacto final como movidos, no eliminados.

Aviso final

Todo artefacto publicado concluye con:

⚠️ Esta salida es preparación para el refinamiento, no un reemplazo. Las decisiones sobre alcance, valor y prioridad pertenecen estrictamente al PO y al equipo.