# ESTÁNDAR DE DOCUMENTACIÓN PARA PROYECTOS

**Versión:** 1.0.0
**Fecha:** 2025-12-05
**Basado en:** Gamilit Documentation Standard
**Aplicabilidad:** Todos los proyectos del workspace

---

## 🎯 PROPÓSITO

Este documento establece el estándar de documentación que todos los proyectos deben seguir para garantizar:

1. **Trazabilidad completa** entre requerimientos, especificaciones, código y tests
2. **Consistencia** en la estructura y nomenclatura
3. **Mantenibilidad** mediante documentación viva con versionado
4. **Navegabilidad** con índices y mapas de contenido

---

## 📋 PRINCIPIOS FUNDAMENTALES

### 1. Trazabilidad Exhaustiva (End-to-End)

```
RF (Requerimiento) → ET (Especificación Técnica) → US (User Story) → Código → Tests
```

- Cada artefacto debe referenciar a sus artefactos relacionados
- El archivo `TRACEABILITY.yml` contiene el mapeo completo con rutas y líneas exactas
- Las referencias cruzadas son bidireccionales

### 2. Modularidad Recursiva

- Cada épica/módulo contiene su propia estructura de subdirectorios
- Mapas de contenido (`_MAP.md`) en cada nivel
- Información consolidada Y detallada simultáneamente

### 3. Documentación Viva

- Cambios registrados con fecha y autor
- Versionado semántico (vX.Y.Z)
- Changelog estructurado en cada documento
- Estados en tiempo real:
  - ✅ Completado/Implementado
  - 📝 Especificado
  - 🔄 En Progreso
  - ⏳ Pendiente

### 4. Multi-Perspectiva

- **Funcional:** Requerimientos (RF)
- **Técnica:** Especificaciones (ET)
- **Usuario:** User Stories (US)
- **Operacional:** Guías y manuales

---

## 📁 ESTRUCTURA DE CARPETAS

### Nivel Proyecto

```
{proyecto}/docs/
├── README.md                           # Índice maestro
├── 00-vision-general/                  # Visión, arquitectura, diseño
├── 01-fase-alcance-inicial/            # Fase 1: MVP/Core
│   ├── {CÓDIGO}-{nombre-épica}/
│   └── ...
├── 02-fase-robustecimiento/            # Fase 2: Consolidación
├── 03-fase-extensiones/                # Fase 3: Features extendidos
├── 04-fase-backlog/                    # Backlog futuro
├── 90-transversal/                     # Documentación transversal
│   ├── arquitectura/
│   ├── metricas/
│   ├── inventarios-database/
│   └── deuda-tecnica/
├── 95-guias-desarrollo/                # Guías técnicas
├── 96-quick-reference/                 # Cheatsheets (<5 min)
├── 97-adr/                             # Architecture Decision Records
├── 98-standards/                       # Estándares del proyecto
└── 99-finiquito/                       # Documentación de entrega
```

### Nivel Épica

```
{CÓDIGO}-{nombre-épica}/
├── README.md                           # Overview de la épica
├── _MAP.md                             # ⭐ Índice navegable con estado
│
├── requerimientos/                     # Requerimientos Funcionales
│   ├── RF-{CODE}-001-{nombre}.md
│   ├── RF-{CODE}-002-{nombre}.md
│   └── ...
│
├── especificaciones/                   # Especificaciones Técnicas
│   ├── ET-{CODE}-001-{nombre}.md
│   ├── ET-{CODE}-ARQUITECTURA.md
│   └── ...
│
├── historias-usuario/                  # User Stories
│   ├── US-{CODE}-001-{nombre}.md
│   ├── US-{CODE}-002-{nombre}.md
│   └── ...
│
├── implementacion/                     # Trazas de implementación
│   ├── PLAN-IMPLEMENTACION.md
│   ├── TRACEABILITY.yml                # ⭐ Mapeo código↔documentación
│   └── INVENTARIO-CAMBIOS.md
│
└── trazabilidad/                       # (Opcional)
    └── MATRIZ-RF-US.md
```

---

## 🏷️ SISTEMA DE NOMENCLATURA

### Prefijos de Fase

| Prefijo | Fase | Descripción |
|---------|------|-------------|
| `00-` | Vision | Visión general, arquitectura, diseño |
| `01-` | Alcance Inicial | MVP/Core features |
| `02-` | Robustecimiento | Consolidación, migraciones |
| `03-` | Extensiones | Features enterprise |
| `04-` | Backlog | Features futuros |
| `90-` | Transversal | Documentación cross-cutting |
| `95-` | Guías | Guías de desarrollo |
| `96-` | Quick Ref | Cheatsheets |
| `97-` | ADR | Architecture Decision Records |
| `98-` | Standards | Estándares |
| `99-` | Finiquito | Documentación de entrega |

### Códigos de Épica

| Prefijo | Significado | Ejemplo |
|---------|-------------|---------|
| `EAI-` | Épica Alcance Inicial | EAI-001-fundamentos |
| `EMR-` | Épica Migración/Robustecimiento | EMR-001-migracion-bd |
| `EXT-` | Épica Extensión | EXT-001-portal-maestros |

### Tipos de Documento

| Prefijo | Tipo | Formato | Ejemplo |
|---------|------|---------|---------|
| `RF-` | Requerimiento Funcional | `RF-{CODE}-{NNN}-{nombre}.md` | RF-AUTH-001-roles.md |
| `ET-` | Especificación Técnica | `ET-{CODE}-{NNN}-{nombre}.md` | ET-AUTH-001-rbac.md |
| `US-` | User Story | `US-{CODE}-{NNN}-{nombre}.md` | US-PM-001-dashboard.md |
| `CA-` | Criterio Aceptación | `CA-{NN}` (dentro de US) | CA-01, CA-02 |
| `ADR-` | Decision Record | `ADR-{NNN}-{titulo}.md` | ADR-001-arquitectura.md |

### Tareas de Implementación

| Prefijo | Stack | Ejemplo |
|---------|-------|---------|
| `DB-` | Database | DB-010: Crear schema |
| `BE-` | Backend | BE-020: Crear service |
| `FE-` | Frontend | FE-030: Crear página |

### Códigos de Dominio Funcional

```
AUTH     → Autenticación y Autorización
GAM      → Gamificación
ANA      → Analytics
ADM      → Administración
TEACH/PM → Portal Maestros
AE       → Admin Extendido
REP      → Reportería
NOTIF    → Notificaciones
CONT     → Contenido/CMS
PERF     → Perfiles
FUND     → Fundamentos
```

---

## 📄 HEADERS ESTÁNDAR

### Header de Requerimiento (RF)

```markdown
# RF-{CODE}-{NNN}: {Título}

**Proyecto:** {NOMBRE}
**Versión:** 1.0
**Última actualización:** {YYYY-MM-DD}
**Estado:** ⏳ Pendiente | 📝 Especificado | ✅ Implementado

---

## 📋 Información del Requerimiento

| Atributo | Valor |
|----------|-------|
| **ID** | RF-{CODE}-{NNN} |
| **Módulo** | {módulo} |
| **Épica** | {CÓDIGO-ÉPICA} |
| **Prioridad** | P0/P1/P2/P3 |
| **Story Points** | {N} SP |
```

### Header de Especificación (ET)

```markdown
# ET-{CODE}-{NNN}: {Título}

**Proyecto:** {NOMBRE}
**Versión:** 1.0
**Última actualización:** {YYYY-MM-DD}
**Estado:** ⏳ Pendiente | 📝 Especificado | ✅ Implementado

---

## 📋 Información de la Especificación

| Atributo | Valor |
|----------|-------|
| **ID** | ET-{CODE}-{NNN} |
| **Requerimiento** | RF-{CODE}-{NNN} |
| **Épica** | {CÓDIGO-ÉPICA} |
| **Stack** | Database/Backend/Frontend/Full-Stack |
| **Complejidad** | Simple/Media/Compleja |
```

### Header de User Story (US)

```markdown
# US-{CODE}-{NNN}: {Título}

**Proyecto:** {NOMBRE}
**Versión:** 1.0
**Última actualización:** {YYYY-MM-DD}
**Estado:** ⏳ Pendiente | 📝 Especificada | 🔄 En Progreso | ✅ Completada

---

## 📋 Información de la Historia

| Atributo | Valor |
|----------|-------|
| **ID** | US-{CODE}-{NNN} |
| **Épica** | {CÓDIGO-ÉPICA} |
| **Requerimiento** | RF-{CODE}-{NNN} |
| **Story Points** | {N} SP |
| **Presupuesto** | ${N,NNN} MXN |
| **Prioridad** | P0/P1/P2/P3 |
```

---

## 📊 ARCHIVOS DE TRAZABILIDAD

### _MAP.md (Mapa de Contenidos)

Cada épica debe tener un `_MAP.md` que incluya:

1. **Información de la épica** (código, fase, presupuesto, SP, estado)
2. **Tabla de Requerimientos** (ID, título, prioridad, estado, link)
3. **Tabla de Especificaciones** (ID, título, stack, estado, link)
4. **Tabla de User Stories** (ID, título, SP, estado, implementación, link)
5. **Métricas de implementación** (páginas, componentes, endpoints, tests)
6. **Historial de cambios** (fecha, descripción, SP, autor)
7. **Próximos pasos** (checklist de pendientes)

### TRACEABILITY.yml

Mapeo exhaustivo que incluye:

```yaml
metadata:          # Info de la épica
documentation:     # Mapeo RF↔ET↔US
database:          # Schemas, tablas, funciones, triggers, RLS
backend:           # Entities, DTOs, services, controllers
frontend:          # Stores, pages, components, hooks
testing:           # Unit, integration, e2e tests
metrics:           # Esfuerzo, presupuesto, calidad
dependencies:      # Épicas relacionadas
changelog:         # Historial de versiones
```

### INVENTARIO-CAMBIOS.md

Tracking de modificaciones por versión:

- Resumen ejecutivo (archivos modificados/creados por capa)
- Detalle por capa (Database, Backend, Frontend)
- Documentación generada
- Métricas del cambio (LOC, SP, tests, cobertura)

---

## 🔗 REFERENCIAS CRUZADAS

### En Requerimientos (RF)

```markdown
## 🔗 Referencias Cruzadas

### Especificación Técnica
📐 [ET-{CODE}-{NNN}: {título}](../especificaciones/ET-{CODE}-{NNN}-{nombre}.md)

### User Stories Relacionadas
- 📝 [US-{CODE}-{NNN}: {título}](../historias-usuario/US-{CODE}-{NNN}-{nombre}.md)

### Implementación
- 🗄️ **Database:** `{ruta}` (líneas {N}-{M})
- 💻 **Backend:** `{ruta}` (líneas {N}-{M})
- 🎨 **Frontend:** `{ruta}` (líneas {N}-{M})

### Mapeo Completo
📊 [TRACEABILITY.yml](../implementacion/TRACEABILITY.yml)
```

### En Especificaciones (ET)

```markdown
## 🔗 Referencias

### Requerimiento Funcional
📋 [RF-{CODE}-{NNN}: {título}](../requerimientos/RF-{CODE}-{NNN}-{nombre}.md)

### User Stories
- 📝 [US-{CODE}-{NNN}](../historias-usuario/US-{CODE}-{NNN}-{nombre}.md)
```

### En User Stories (US)

```markdown
## 🔗 Referencias

### Requerimiento Funcional
📋 [RF-{CODE}-{NNN}](../requerimientos/RF-{CODE}-{NNN}-{nombre}.md)

### Especificación Técnica
📐 [ET-{CODE}-{NNN}](../especificaciones/ET-{CODE}-{NNN}-{nombre}.md)
```

---

## 📈 MÉTRICAS Y VERSIONADO

### Prioridades

| Código | Nivel | Descripción |
|--------|-------|-------------|
| P0 | Crítica | Bloqueante, debe hacerse primero |
| P1 | Alta | Importante para el MVP |
| P2 | Media | Deseable pero no bloqueante |
| P3 | Baja | Nice-to-have |

### Story Points

| SP | Complejidad | Tiempo Estimado |
|----|-------------|-----------------|
| 1-2 | Simple | 1-4 horas |
| 3-5 | Media | 5-12 horas |
| 8-13 | Compleja | 16-32 horas |
| 21+ | Épica | Debe desglosarse |

### Estados

| Emoji | Estado | Descripción |
|-------|--------|-------------|
| ⏳ | Pendiente | No iniciado |
| 📝 | Especificado | Documentado pero no implementado |
| 🔄 | En Progreso | Implementación en curso |
| ✅ | Completado | Implementado y verificado |
| ❌ | Bloqueado | Con impedimentos |

### Versionado Semántico

```
vX.Y.Z

X = Major: Cambios incompatibles/replanteamiento
Y = Minor: Nuevas funcionalidades (compatible)
Z = Patch: Correcciones y cambios menores
```

### Changelog

Cada documento debe incluir al final:

```markdown
## 📜 Changelog

| Fecha | Versión | Autor | Cambios |
|-------|---------|-------|---------|
| YYYY-MM-DD | 1.0 | {autor} | Creación inicial |
| YYYY-MM-DD | 1.1 | {autor} | {descripción del cambio} |
```

---

## 🔍 VALIDACIÓN DE DOCUMENTACIÓN

### Checklist Pre-Implementación

Antes de iniciar implementación, verificar:

- [ ] README.md de épica existe
- [ ] _MAP.md con índice completo
- [ ] Todos los RF documentados
- [ ] Todos los ET documentados
- [ ] Todas las US documentadas
- [ ] TRACEABILITY.yml inicial generado
- [ ] Referencias cruzadas verificadas
- [ ] Dependencias identificadas

### Checklist Post-Implementación

Después de implementar, verificar:

- [ ] TRACEABILITY.yml actualizado con rutas exactas
- [ ] INVENTARIO-CAMBIOS.md actualizado
- [ ] _MAP.md con estados actualizados
- [ ] Métricas registradas (LOC, tests, cobertura)
- [ ] Changelog actualizado en cada documento modificado

---

## 📚 REFERENCIAS

### Proyecto de Referencia
- **Gamilit:** `/home/isem/workspace/projects/gamilit/docs/`
- Implementación más completa del estándar
- 165+ documentos, 12+ épicas

### Agente Responsable
- **Requirements-Analyst:** Genera documentación inicial
- **Documentation-Validator:** Valida completitud y consistencia

### Templates
Ver templates completos en:
- `/home/isem/workspace/core/orchestration/agents/PROMPT-REQUIREMENTS-ANALYST.md`

---

**Versión:** 1.0.0
**Última actualización:** 2025-12-05
**Autor:** Requirements-Analyst Standard v2.0
