# DIRECTIVA: DOCUMENTACIÓN AGILE

**Versión:** 1.0.0
**Fecha:** 2025-12-05
**Aplicable a:** Todos los agentes y proyectos
**Estado:** OBLIGATORIO

---

## OBJETIVO

Establecer los estándares y procesos para documentación Agile en todos los proyectos, incluyendo:
- Épicas y su estructura
- Historias de Usuario (HU/US)
- Tareas técnicas
- Definition of Ready (DoR) y Definition of Done (DoD)
- Backlog y Sprint planning

---

## JERARQUÍA DE TRABAJO

```
ÉPICA (Epic)
    │
    ├── Historia de Usuario 1 (US)
    │       ├── Tarea DB-001
    │       ├── Tarea BE-001
    │       └── Tarea FE-001
    │
    ├── Historia de Usuario 2 (US)
    │       ├── Tarea DB-002
    │       ├── Tarea BE-002
    │       └── Tarea FE-002
    │
    └── Historia de Usuario N (US)
            └── Tareas...
```

### Relación con Requerimientos

| Nivel | Documento | Ubicación |
|-------|-----------|-----------|
| Requerimiento Funcional | RF-{MOD}-{NNN}.md | `docs/03-requerimientos/RF-{modulo}/` |
| Épica | EPIC-{ID}.md | `docs/05-user-stories/epicas/` |
| Historia de Usuario | US-{MOD}-{NNN}.md | `docs/05-user-stories/US-{modulo}/` |
| Tarea Técnica | {GRUPO}-{NNN} | `orchestration/agentes/{grupo}/{EPIC-ID}/` |

---

## NOMENCLATURA

### IDs de Épicas

**Formato:** `{FASE}-{NNN}`

| Fase | Prefijo | Ejemplo |
|------|---------|---------|
| Fase 1 - Alcance Inicial | EAI | EAI-001, EAI-002 |
| Fase 2 - Robustecimiento | EMR | EMR-001 |
| Fase 3 - Extensiones | EXT | EXT-001, EXT-010 |
| Fase 4 - Enterprise | ENT | ENT-001 |

### IDs de Historias de Usuario

**Formato:** `US-{MODULO}-{NNN}`

| Módulo | Ejemplo |
|--------|---------|
| AUTH | US-AUTH-001 |
| USERS | US-USERS-001 |
| PROJECTS | US-PROJECTS-001 |
| GAMIFICATION | US-GAM-001 |

### IDs de Tareas Técnicas

**Formato:** `{GRUPO}-{NNN}`

| Grupo | Prefijo | Responsable |
|-------|---------|-------------|
| Database | DB | NEXUS-DATABASE |
| Backend | BE | NEXUS-BACKEND |
| Frontend | FE | NEXUS-FRONTEND |
| Testing | TEST | Agente correspondiente |
| DevOps | DO | DevOps-Agent |

---

## DEFINITION OF READY (DoR)

### Para Épicas

Una épica está **Ready** cuando:

- [ ] Tiene descripción clara del objetivo de negocio
- [ ] Historias de usuario identificadas (al menos las principales)
- [ ] Dependencias con otras épicas documentadas
- [ ] Story points estimados (nivel épica)
- [ ] Stakeholders identificados
- [ ] Sin bloqueadores activos
- [ ] Prioridad definida

### Para Historias de Usuario

Una historia está **Ready** cuando:

- [ ] Formato "Como/Quiero/Para" completo
- [ ] Criterios de aceptación definidos (formato Gherkin)
- [ ] Story points estimados
- [ ] Dependencias identificadas
- [ ] Mockups/wireframes disponibles (si aplica)
- [ ] API spec disponible (si requiere backend)
- [ ] Sin bloqueadores
- [ ] Tareas técnicas desglosadas

### Para Tareas Técnicas

Una tarea está **Ready** cuando:

- [ ] Especificación técnica clara
- [ ] Archivos a crear/modificar identificados
- [ ] Dependencias de otras tareas identificadas
- [ ] Estimación en horas
- [ ] Criterios de aceptación técnicos
- [ ] Comandos de validación definidos

---

## DEFINITION OF DONE (DoD)

### Para Épicas

Una épica está **Done** cuando:

- [ ] Todas las historias de usuario completadas
- [ ] Todos los criterios de aceptación de la épica cumplidos
- [ ] Integración DB-Backend-Frontend verificada
- [ ] Cobertura de tests > 80%
- [ ] Documentación actualizada
- [ ] Demo realizada al Product Owner
- [ ] Product Owner aprobó
- [ ] Desplegado en ambiente de staging

### Para Historias de Usuario

Una historia está **Done** cuando:

- [ ] Todas las tareas técnicas completadas
- [ ] Todos los criterios de aceptación verificados
- [ ] Tests unitarios escritos y pasando
- [ ] Tests de integración pasando (si aplica)
- [ ] Code review aprobado
- [ ] Documentación actualizada
- [ ] Inventarios actualizados (MASTER_INVENTORY.yml)
- [ ] Traza registrada
- [ ] QA validó funcionalidad
- [ ] Sin bugs críticos abiertos

### Para Tareas Técnicas

Una tarea está **Done** cuando:

- [ ] Código implementado según especificación
- [ ] Compilación sin errores
- [ ] Tests pasando
- [ ] Comentarios/documentación en código
- [ ] Comandos de validación ejecutados exitosamente
- [ ] Inventario correspondiente actualizado
- [ ] Traza registrada en TRAZA-TAREAS-{GRUPO}.md
- [ ] Log de ejecución documentado

---

## ESTIMACIÓN

### Story Points (Fibonacci)

| SP | Complejidad | Tiempo Aproximado | Ejemplo |
|----|-------------|-------------------|---------|
| 1 | Trivial | < 2h | Fix typo, agregar campo simple |
| 2 | Muy Simple | 2-4h | CRUD básico de 1 entidad |
| 3 | Simple | 4-8h | Funcionalidad con validaciones |
| 5 | Media | 1-2 días | Feature con múltiples componentes |
| 8 | Compleja | 3-4 días | Feature cross-stack |
| 13 | Muy Compleja | 1 semana | Epic pequeño |
| 21 | Enorme | > 1 semana | Debe dividirse |

### Tareas Técnicas (Horas)

| Tipo | Rango | Ejemplo |
|------|-------|---------|
| Trivial | 0.5-1h | Agregar columna, ajustar estilo |
| Simple | 1-2h | Crear tabla básica, componente simple |
| Media | 2-4h | Service con lógica, página con forms |
| Compleja | 4-8h | Módulo completo, integración API |

**Regla:** Una tarea técnica NO debe superar 8 horas. Si supera, debe dividirse.

---

## TEMPLATES

### Ubicación de Templates

```
core/orchestration/templates/
├── TEMPLATE-EPICA.md
├── TEMPLATE-HISTORIA-USUARIO.md
├── TEMPLATE-TAREA-TECNICA.md
├── TEMPLATE-ANALISIS.md
├── TEMPLATE-PLAN.md
└── TEMPLATE-VALIDACION.md
```

### Uso Obligatorio

| Documento | Template | Agente Responsable |
|-----------|----------|-------------------|
| Épica | TEMPLATE-EPICA.md | Requirements-Analyst |
| Historia de Usuario | TEMPLATE-HISTORIA-USUARIO.md | Requirements-Analyst |
| Tarea Database | TEMPLATE-TAREA-TECNICA.md | Database-Agent |
| Tarea Backend | TEMPLATE-TAREA-TECNICA.md | Backend-Agent |
| Tarea Frontend | TEMPLATE-TAREA-TECNICA.md | Frontend-Agent |

---

## FLUJO DE TRABAJO

### 1. Definición de Épica

```
Requirements-Analyst:
1. Lee documentación de requerimientos (docs/03-requerimientos/)
2. Crea épica usando TEMPLATE-EPICA.md
3. Identifica historias de usuario principales
4. Estima SP a nivel épica
5. Documenta dependencias
```

### 2. Desglose en Historias

```
Requirements-Analyst:
1. Por cada funcionalidad principal, crea US usando TEMPLATE-HISTORIA-USUARIO.md
2. Define criterios de aceptación (formato Gherkin)
3. Estima SP por historia
4. Identifica tareas técnicas por stack
```

### 3. Asignación de Tareas

```
Feature-Developer / Agente Principal:
1. Valida DoR de historias
2. Asigna tareas a agentes especializados:
   - DB-XXX → NEXUS-DATABASE
   - BE-XXX → NEXUS-BACKEND
   - FE-XXX → NEXUS-FRONTEND
3. Coordina orden de ejecución
```

### 4. Ejecución de Tarea

```
Agente Especializado:
1. Valida DoR de la tarea
2. Ejecuta según especificación
3. Documenta log de ejecución
4. Valida con comandos definidos
5. Actualiza inventario
6. Registra en traza
7. Marca como Done cuando cumple DoD
```

### 5. Validación de Historia

```
QA / Agente Validador:
1. Verifica criterios de aceptación
2. Ejecuta tests
3. Documenta resultado
4. Si PASS → Historia Done
5. Si FAIL → Regresa a desarrollo con feedback
```

### 6. Cierre de Épica

```
Feature-Developer / Agente Principal:
1. Verifica todas las historias Done
2. Ejecuta validación integral
3. Actualiza MASTER_INVENTORY.yml
4. Demo al Product Owner
5. Marca épica como Done
```

---

## RELACIÓN CON INVENTARIOS Y TRAZAS

### Actualización de Inventarios

| Evento | Inventario a Actualizar |
|--------|-------------------------|
| Tarea DB completada | DATABASE_INVENTORY.yml, MASTER_INVENTORY.yml |
| Tarea BE completada | BACKEND_INVENTORY.yml, MASTER_INVENTORY.yml |
| Tarea FE completada | FRONTEND_INVENTORY.yml, MASTER_INVENTORY.yml |
| Historia completada | MASTER_INVENTORY.yml (status del módulo) |
| Épica completada | DEPENDENCY_GRAPH.yml (marcar como done) |

### Registro en Trazas

| Evento | Traza |
|--------|-------|
| Tarea DB | TRAZA-TAREAS-DATABASE.md |
| Tarea BE | TRAZA-TAREAS-BACKEND.md |
| Tarea FE | TRAZA-TAREAS-FRONTEND.md |
| Historia/Épica | TRAZA-REQUERIMIENTOS.md |

---

## BACKLOG

### Estructura del Backlog

```yaml
# orchestration/backlog/PRODUCT-BACKLOG.yml

backlog:
  epicas:
    - id: EAI-001
      nombre: "Fundamentos Auth"
      prioridad: P0
      estado: Done
      historias:
        - US-AUTH-001: Done
        - US-AUTH-002: Done

    - id: EAI-003
      nombre: "Sistema de Gamificación"
      prioridad: P0
      estado: In Progress
      historias:
        - US-GAM-001: Done
        - US-GAM-002: In Progress
        - US-GAM-003: Ready
        - US-GAM-004: Backlog
```

### Sprint Backlog

```yaml
# orchestration/backlog/SPRINT-{N}-BACKLOG.yml

sprint:
  numero: 5
  inicio: 2025-12-01
  fin: 2025-12-14

  objetivo: "Completar módulo de gamificación básico"

  historias:
    - id: US-GAM-002
      sp: 5
      asignado: NEXUS-BACKEND
      estado: In Progress

    - id: US-GAM-003
      sp: 3
      asignado: NEXUS-FRONTEND
      estado: Ready

  capacidad_total: 40 SP
  comprometido: 32 SP
```

---

## CHECKLIST DE CUMPLIMIENTO

### Antes de Iniciar Trabajo en Épica

- [ ] Épica documentada con TEMPLATE-EPICA.md
- [ ] DoR de épica cumplido
- [ ] Historias principales identificadas

### Antes de Iniciar Historia

- [ ] Historia documentada con TEMPLATE-HISTORIA-USUARIO.md
- [ ] DoR de historia cumplido
- [ ] Tareas técnicas desglosadas

### Antes de Iniciar Tarea

- [ ] Tarea documentada (puede ser inline en historia o separada)
- [ ] DoR de tarea cumplido
- [ ] Dependencias completadas

### Al Completar Tarea

- [ ] DoD de tarea cumplido
- [ ] Inventario actualizado
- [ ] Traza registrada

### Al Completar Historia

- [ ] DoD de historia cumplido
- [ ] Criterios de aceptación verificados
- [ ] QA aprobado

### Al Completar Épica

- [ ] DoD de épica cumplido
- [ ] Demo realizada
- [ ] Product Owner aprobó

---

## REFERENCIAS

- [TEMPLATE-EPICA.md](../templates/TEMPLATE-EPICA.md)
- [TEMPLATE-HISTORIA-USUARIO.md](../templates/TEMPLATE-HISTORIA-USUARIO.md)
- [TEMPLATE-TAREA-TECNICA.md](../templates/TEMPLATE-TAREA-TECNICA.md)
- [DIRECTIVA-DOCUMENTACION-OBLIGATORIA.md](./DIRECTIVA-DOCUMENTACION-OBLIGATORIA.md)
- [PROMPT-REQUIREMENTS-ANALYST.md](../agents/PROMPT-REQUIREMENTS-ANALYST.md)

---

**Versión:** 1.0.0
**Creada por:** Architecture-Analyst
**Aprobada por:** Tech Lead
**Última actualización:** 2025-12-05
