AI agent skill · by @mohitagw15856

User Story Writer

Escribir historias de usuario bien estructuradas con criterios de aceptación y casos extremos. Úsalo cuando te pidan escribir historias de usuario, crear tickets a partir de un resumen de características, convertir un PRD en historias o redactar criterios de aceptación. Produce historias listas para estimar en formato estándar con criterios de aceptación claros, casos extremos y definición de hecho.

Archived 2026-10-23 · Source updated 2026-10-11 · License: MIT. Check the original repository for the latest version.

SKILL.md instructions

# 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"