--- name: mohitagw15856/user-story-writer source: https://app.decimal.ai/s/mohitagw15856-user-story-writer@3/SKILL.md source_sha256: 33cbfce542d5 --- # 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"