Agile Method

Este es el manual del método: la guía de cómo se procesa cada nuevo encargo de un proyecto —desde que llega como una idea hasta que es una solución técnica documentada y rastreable en Jira—. Define el vocabulario, la jerarquía, el flujo y las reglas.

Es el mismo método en todos los proyectos: se replica tal cual desde este portal (hub + herencia), para que cualquier colaborador —humano o IA— encuentre la misma estructura, el mismo vocabulario y las mismas reglas en todos lados. Y como el MD es la fuente de verdad que leen los agentes (Claude/Kimi/Codex), este manual es a la vez guía humana y protocolo operativo de la IA: cuando llega un encargo, aquí está cómo convertirlo en Epic/Story y dónde registrarlo.

De dónde viene

Este método no es nuevo: ya existía y estaba maduro apuntando a Confluence (create_epic.py, create_agile_structure.py, convert_to_livedocs.py). Docu v2 lo migra a docs-as-code (MD + Starlight) y lo liga a Jira. Lo llamaba Live Documents — es decir, ya era living documentation antes de que tuviera nombre.

Vocabulario

Sigla	Qué es	Dónde vive
AM	Agile Method — este manual	La página que estás leyendo
LD	Live Document — un Epic documentado	Hijo directo del índice del proyecto
EO	Epic Overview — propósito, objetivo de negocio, alcance, no-alcance	Sección dentro del LD (el Epic)
US	User Stories — la User Story en español	Sección dentro de cada Story
SR	Story Refinement — criterios, casos límite, dependencias	Sección dentro de cada Story
SD	Solution Design — problem, solution, backend/frontend (si aplica), AI support, restricciones, rabbit holes, no-gos, references	Sección dentro de cada Story

La jerarquía

Proyecto (dominio padre)
  ├── Agile Method (este manual, heredado del global)
  ├── [ENTIDAD-A]              ← Epic = Live Document = un módulo/entidad
  │     ├── Story 1            ← página única: US + SR + SD integrados
  │     ├── Story 2
  │     └── ...
  └── [ENTIDAD-B]              ← otro Epic
        └── ...

• Epic = módulo o entidad de negocio. Se nombra entre corchetes: [CONTACTO], [AUTENTICACION], [FACTURACION]. Los Epics no se solapan: cada uno cubre un módulo distinto. El Epic ES el nivel raíz del trabajo — no hace falta un nivel “Iniciativa” por encima; encima de los Epics solo está el proyecto.
• Story = una pieza de valor entregable, documentada en una sola página que contiene las tres secciones integradas (US → SR → SD). Es hija de su Epic.
• Task = desglose técnico de una Story (opcional, cuando conviene partirla).
• Petición = bandeja de entrada: lo que llega antes de volverse Story.

El flujo: de un encargo a una Story documentada

Así viaja cualquier encargo nuevo, desde que entra hasta que se implementa:

1. Entra como Petición. Todo lo que llega —de una conversación, junta, correo o Jira— aterriza primero en la bandeja de entrada, sin refinar.
2. Se clasifica a un Epic. ¿A qué módulo/entidad pertenece? Si el Epic ya existe, la Petición se vuelve una Story suya; si no, se crea el Epic (con su Epic Overview) y luego la Story.
3. Se escribe la Story — sección US. El qué de negocio en formato “Como/quiero/para”, acordado con quien lo pidió.
4. Se refina — sección SR. Criterios de aceptación, casos límite y dependencias. Aquí nace el issue Story en Jira.
5. Se diseña — sección SD. Backend, frontend, AI support y restricciones (DS-First). Aquí nacen los Task (child issues) en Jira.
6. Se implementa y se mueve en el tablero. El estado del front-matter sigue el sprint; el MD queda como la verdad del conocimiento.

Para la IA

Cuando un encargo surge en la conversación, este flujo es tu protocolo: clasifícalo a su Epic, redacta o amplía la Story en el MD del docu del proyecto que corresponda, y liga Jira según la sección. El MD es tu contexto de entrada y tu entregable de salida.

Las tres secciones de una Story: US → SR → SD

No son estados ni pasos de un proceso aparte: son las tres secciones que conviven en la misma página de la Story. Así se lee su evolución completa de un vistazo — del qué de negocio al cómo técnico.

1. User Stories (US) — el qué de negocio

La necesidad en lenguaje de negocio, sin tecnicismos. Formato obligatorio:

“Como [rol], quiero [capacidad], para [beneficio de negocio].”

• Contiene: la historia de usuario y su valor de negocio.
• Jira: no se liga nada aquí; es el backlog de negocio.
• Regla: es inmutable una vez aprobada. Si cambia, se crea una nueva Story que referencia a la original (como un ADR superseded).

2. Story Refinement (SR) — el cómo de aceptación

Qué debe cumplirse para dar la Story por buena, qué puede salir mal y de qué depende.

• Contiene: criterios de aceptación, casos límite y dependencias.
• Jira: aquí sí se liga el issue Story.

3. Solution Design (SD) — el cómo técnico

Cómo se construye, siempre dentro del alcance definido en el Epic Overview. Sus subsecciones, en orden:

Subsección	Para qué	Regla
Problem	1-3 bullets del alcance ya acotado en el SR	Enlaza, no repite el por qué — eso ya vive en US/SR.
Solution	Narrativa + diagrama de baja fidelidad del enfoque propuesto	Suficiente para construir, no una spec pixel-perfect — no le amarra las manos a quien ejecuta.
Backend	Arquitectura, modelo de datos/API, dependencias, seguridad, testing	Se incluye solo si el feature tiene trabajo real de ese lado — criterio del developer, no checklist obligatoria.
Frontend	Component tree, integración con API, estado, edge cases	Mismo criterio que Backend.
AI Support	Si el feature usa o habilita capacidades de IA	Se omite si no aplica.
Restricciones	Límites de negocio, técnicos o legales a respetar	—
Rabbit Holes	Riesgos técnicos puntuales a anticipar antes de construir	Para que el developer no se atore a medio build.
No-gos	Qué queda explícitamente fuera de alcance	Evita scope creep durante la construcción.
References	Links a incidentes, dashboards, hilos, specs externas	Solo links, nunca contenido pegado — mantiene la página escaneable.

• Jira: se ligan los child issues técnicos (Task).
• Regla — DS-First: los componentes de UI se documentan contra el Design System del proyecto antes de implementarlos.

De dónde viene esta estructura

Backend/Frontend como secciones propias (no una genérica) replica el patrón real de Uber: templates de RFC distintos para Service vs Mobile, cada uno con su propio set de secciones. Rabbit Holes/No-gos vienen de los pitches de Shape Up (Basecamp) — acotan riesgo y alcance sin sobre-especificar la implementación. “Enlaza, no repitas” es la práctica que evita que la trazabilidad se vuelva ilegible por duplicación entre US/SR/SD.

El estado del front-matter (propuesta → refinamiento → ready → in-progress → review → done) es otra cosa: es el status del tablero, que se sincroniza con el sprint en Jira. Una Story puede estar ready y aun así tener su sección SD a medio escribir — son ejes distintos.

Relación con Jira

Jira es la verdad del tracking (sprints, tablero, estados). El MD es la verdad del conocimiento (qué, por qué, cómo). Una sola dirección de verdad por cosa; nada de sincronizar todo en ambos sentidos.

En el MD (Docu)	En Jira
Epic (LD) con EO	Epic — 1:1 con el Epic; la key va en la tabla de generales
Sección US	(nada: es backlog de negocio, no se liga)
Sección SR	Story issue (la Story refinada)
Sección SD	Task / child issues (el desglose técnico)

Teniendo el conector de Jira por API, los Epics y Stories se pueden crear desde la conversación mientras definimos requerimientos, y quedar ligados aquí.

Reglas de oro

#	Regla
1	Idioma español. Excepción: los términos del método se dejan en inglés y no se traducen — Agile Method, Epic, Story, User Story, Story Refinement, Solution Design, Epic Overview, Task.
2	Epic = módulo/entidad, entre corchetes, sin solapamiento entre Epics.
3	Story = página única integrada (US + SR + SD). No se parte en subpáginas.
4	INVEST: cada Story debe ser Independiente, Negociable, Valiosa, Estimable, Pequeña y Testeable.
5	Inmutabilidad: una Story aprobada no se reescribe. Si cambia, se crea una nueva Story que referencia a la original (mismo principio que un ADR “superseded”).
6	Jira nunca se liga en US — solo en SR (Story) y SD (Task).
7	Epic Jira = Epic Docu, 1:1.
8	DS-First: en Solution Design, los componentes de UI se documentan contra el Design System del proyecto antes de implementarlos.
9	Backend/Frontend no son obligatorios los dos: en Solution Design se documenta solo el lado que tiene trabajo real — criterio del developer, no una checklist rígida.
10	References es solo links: nunca se pega contenido completo de otra fuente dentro de la Story — mantiene la página escaneable.

Front-matter (contrato validado en build)

El front-matter captura la tabla de generales; el cuerpo lleva las secciones EO/US/SR/SD como encabezados. Starlight valida estos campos contra el esquema Zod de src/content.config.ts: un estado o tipo inválido rompe la compilación.

---
title: "CONT-001 · Envío del formulario de contacto"
tipo: story             # epic | story | task | peticion | manual
epic: EPIC-CONTACTO     # a qué Epic pertenece
id: CONT-001            # código de la Story
estado: ready           # propuesta | refinamiento | ready | in-progress | review | done | bloqueada
prioridad: alta         # baja | media | alta | critica
kudos: 5                # estimación de esfuerzo (antes "Story Points")
jira: PGM-123           # link al issue en Jira
criterios_aceptacion:
  - El mensaje se entrega al correo configurado.
creado: 2026-10-12
---

Ejemplo del método

Para ver el método aplicado a un caso real y entendible, revisa el Epic de ejemplo [CONTACTO] y su Story completa:

• Epic · [CONTACTO] — la tabla de generales + Epic Overview + lista de Stories.
• Story · CONT-001 — una Story completa con US → SR → SD integrados. Cópiala como plantilla.

Dónde encaja la doc estable (Diátaxis)

El Agile Method cubre el flujo (Epics y Stories). La documentación estable de cada proyecto (arquitectura, dominio, cómo-se-usa) conviene organizarla con Diátaxis: separar tutorial, how-to, referencia y explicación. La clave: no mezclar el “cómo se armó” (explicación / Solution Design) con el “cómo se usa” (how-to). Son lectores y momentos distintos.