Skill User Story Writer

Esta habilidad produce historias de usuario listas para producción a partir de un resumen de características, una sección de PRD o una descripción verbal. Cada historia sigue el formato estándar con un claro quién/qué/por qué, criterios de aceptación conductuales en formato Given/When/Then, casos extremos y definición de hecho. El resultado está listo para copiar y pegar en Jira, Linear o tu herramienta de planificación.

Entradas Requeridas

Pide al usuario estos datos si no están proporcionados:

• Característica o cambio a desglosar en historias — copia el resumen, sección de PRD o describe la característica
• Tipos de usuario / personas involucradas (p. ej. administrador, usuario final, invitado, consumidor de API)
• Alcance — ¿escribimos una historia o desglozamos una épica en un conjunto completo de historias?
• Preferencia de formato de criterios de aceptación — Given/When/Then, lista de verificación con viñetas o ambos?
• Restricciones técnicas o notas — cualquier cosa que el equipo de ingeniería haya señalado y que deba conformar las historias

Estructura del Resultado

Para cada historia:

Historia: Título breve — verbo + sustantivo, p. ej. "Filtrar resultados de búsqueda por rango de fechas"]

Épica: Nombre de la épica principal — p. ej. "Búsqueda Avanzada"] ID de Historia: ID de Jira/Linear — deja en blanco si aún no se ha creado] Prioridad: P1 / P2 / P3] Puntos de historia: Deja en blanco — para que el equipo de ingeniería estime]

Historia de Usuario

> Como tipo de usuario específico — no "usuario"], > Quiero acción concreta que desean realizar], > Para el resultado que logran — valor de negocio, no descripción de la característica].

Ejemplo: > Como gerente de cuenta, > Quiero filtrar mi lista de clientes por fecha de último contacto, > Para poder identificar rápidamente los clientes con los que no he hablado en más de 30 días y priorizar el seguimiento.

Contexto

1–3 oraciones de contexto que no están en la historia de usuario: cuándo importa esta historia, qué la desencadena, cómo se ajusta en un flujo más amplio. Esto ayuda a los ingenieros a entender el por qué antes de que pregunten.]

Criterios de Aceptación

Formato: Given / When / Then

Cada criterio prueba un comportamiento específico. Escribe un GWT por resultado observable — no un GWT para toda la característica.

CA1: Nombre corto para este criterio]

Given [estado inicial o contexto]
When [acción del usuario]
Then [comportamiento observable del sistema]

CA2: Nombre corto]

Given [...]
When [...]
Then [...]

CA3: Nombre corto]

Given [...]
When [...]
Then [...]

Casos Extremos

Lista escenarios que no son obvios pero que deben manejarse. Estos se convierten en ACs adicionales o notas para ingeniería.]

• ] Caso extremo 1]: p. ej. El usuario aplica un filtro de fecha que devuelve 0 resultados — mostrar estado vacío con mensaje claro y una acción "limpiar filtros"]
• ] Caso extremo 2]: p. ej. El usuario tiene >10,000 clientes — el filtro no debe degradar el tiempo de carga >200ms]
• ] Caso extremo 3]: p. ej. El filtro de fecha persiste en la actualización de página — o explícitamente no debe si esa es la decisión]
• ] Caso extremo de permisos]: p. ej. Los usuarios de solo lectura pueden ver el filtro pero no pueden guardar presets de filtro]

Fuera de Alcance

Indica explícitamente qué NO cubre esta historia — previene el aumento de alcance y clarifica dónde comienza la siguiente historia.]

• Guardar y compartir presets de filtro (historia separada — ver Historia X])
• Acciones en masa en resultados filtrados
• Exportar lista de clientes filtrada a CSV

Definición de Hecho

• ] Todos los criterios de aceptación se cumplen
• ] Casos extremos manejados (o explícitamente diferidos con un nuevo ticket abierto)
• ] Pruebas unitarias escritas para cada CA
• ] Funciona en viewport móvil (si aplica)
• ] Accesibilidad: navegable con teclado y compatible con lectores de pantalla
• ] Los estados de error se manejan y el texto está aprobado
• ] Producto y diseño han revisado en staging
• ] Sin errores en consola en la compilación de producción

Plantilla de Desglozamiento de Épica

Si el usuario proporciona una épica o resumen de características, desglózala en un conjunto completo de historias antes de escribirlas:

Épica: Nombre] Objetivo: ¿Qué resultado logra completar esta épica?] Historias:

| # | Historia | Notas | Dependencias | |---|---|---|---| | 1 | Historia del camino feliz principal — la versión más simple de la característica que entrega valor] | | | | 2 | Historia de validación / manejo de errores] | | Depende de #1 | | 3 | Historia de caso extremo o usuario avanzado] | | Depende de #1 | | 4 | Historia de administrador o configuración] | | | | 5 | Historia de rendimiento o escala — si aplica] | | Depende de #1 |

Orden sugerido de sprint: ¿Qué historias son P1 para MVP? ¿Cuáles pueden seguir en un sprint posterior?]

Anti-patrones Comunes de Historias — y Soluciones

Usa estos para revisar historias antes de entregarlas a ingeniería:

| Anti-patrón | Ejemplo | Solución | |---|---|---| | Solución en la historia | "Como usuario quiero un filtro desplegable" | Elimina la decisión de UI — "Como usuario quiero filtrar por rango de fechas" | | "Para qué" vago | "para que sea más fácil de usar" | Hazlo específico — "para que pueda priorizar el seguimiento sin abrir cada registro manualmente" | | Demasiado grande | La historia cubre 5 flujos de usuario distintos | Divide en historias separadas por flujo | | Sin criterios de aceptación | La historia solo tiene descripción | Agrega al menos 3 criterios GWT antes de que ingeniería empiece | | ACs que prueban la solución, no el comportamiento | "Given el desplegable está abierto, When selecciono una opción" | Prueba el resultado — "Given he aplicado un filtro de fecha, When veo mis resultados, Then solo aparecen clientes contactados en ese rango de fechas" | | Falta estado vacío | Sin CA para qué sucede con 0 resultados | Agrégalo — los estados vacíos son parte de la característica | | Falta estado de error | Sin CA para fallo de red o entrada inválida | Agrega explícitamente ACs de manejo de errores |

Ejemplo: Conjunto Completo de Historias para una Característica

Resumen de característica: "Permitir a los usuarios exportar su historial de facturas como PDF o CSV"

Historia 1: Exportar lista de facturas como CSV

> Como administrador de finanzas, > Quiero exportar mi historial de facturas como archivo CSV, > Para poder importarlo en nuestro software de contabilidad sin entrada manual de datos.

CA1: Exportación exitosa

Given estoy en la página de Facturas con al menos una factura
When hago clic en "Exportar" y selecciono "CSV"
Then se descarga un archivo CSV que contiene todas las facturas visibles con columnas: ID de Factura, Fecha, Monto, Estado, Nombre del Cliente

CA2: Estado vacío

Given estoy en la página de Facturas sin facturas
When hago clic en "Exportar"
Then el botón de exportar está deshabilitado y un tooltip dice "No hay facturas para exportar"

CA3: Exportación filtrada

Given he aplicado un filtro de fecha mostrando facturas de enero 2026 solo
When hago clic en "Exportar" y selecciono "CSV"
Then la exportación contiene solo facturas de enero 2026 — no todas las facturas

Casos extremos:

• ] Exportar con >10,000 facturas — debe completarse en <30s o mostrar un indicador de progreso
• ] Exportación activada en móvil — se descarga a la ubicación de descarga predeterminada del dispositivo

Fuera de alcance: Exportación a PDF (Historia 2), exportaciones programadas (épica futura)

Historia 2: Exportar lista de facturas como PDF

> Como administrador de finanzas, > Quiero exportar mi historial de facturas como PDF formateado, > Para poder compartir un resumen profesional con nuestro contador.

... los ACs siguen el mismo patrón ...]

Verificaciones de Calidad

• ] Cada historia tiene un tipo de usuario específico — no "un usuario" o "el sistema"
• ] El "para" explica el valor de negocio — no solo descripción de la característica
• ] Cada CA prueba un resultado observable — no un conjunto de comportamientos
• ] Los estados vacíos, estados de error y casos extremos se manejan explícitamente
• ] El alcance fuera se documenta — no se asume
• ] Las historias son independientes — pueden entregarse individualmente sin depender de trabajo no lanzado (excepto donde se indica explícitamente)

Anti-patrones

• ] No escribas historias de usuario desde una perspectiva técnica — cada historia debe estar desde el punto de vista del usuario y establecer su objetivo
• ] No escribas criterios de aceptación que sean inprobables — cada criterio debe tener una condición clara de aprobación/fallo
• ] No crees historias demasiado grandes para completar en un solo sprint — desgloza épicas en historias estimables e independientemente entregables
• ] No omitas casos extremos — los caminos infelices y estados de error son obligatorios, no opcionales
• ] No saltes la Definición de Hecho — sin ella, "hecho" significa cosas diferentes para diferentes personas

Frases Desencadenantes de Ejemplo

• "Escribe historias de usuario para característica] a partir de este resumen"
• "Desgloza esta sección de PRD en historias de usuario con criterios de aceptación"
• "Convierte estos requisitos de características en tickets de Jira"
• "Escribe las historias de usuario y ACs para nombre de característica]"
• "Desgloza esta épica en historias individuales listas para planificación de sprint"