@damenor/agent-docs 0.1.0

package/templates/modules/explanation/docs/explanation/architecture.md

@@ -0,0 +1,138 @@
+---
+created: "2026-05-07"
+updated: "2026-05-07"
+status: active
+type: explanation
+tags: [architecture, system-design, explanation]
+---
+
+# Arquitectura del Sistema
+
+> **Propósito**: Este documento explica la arquitectura del sistema — no *cómo* usarlo, sino *por qué* está diseñado así. Para detalles de implementación, consulta el código fuente. Para decisiones concretas, consulta los ADRs en `docs/adr/`.
+
+## Visión General
+
+[Breve descripción del sistema: qué hace, quién lo usa, cómo se relaciona con otros sistemas]
+
+```mermaid
+flowchart TD
+    Client["🌐 Cliente<br/>(Browser / App / API Consumer)"]
+    CDN["CDN / Load Balancer"]
+    FE["Frontend<br/>[Framework]<br/>SSR/SPA · Routing · State"]
+    BE["API / Backend<br/>[Framework]<br/>REST API · Auth · Business logic"]
+    DB["🗄️ Base de datos<br/>[PostgreSQL]"]
+    Cache["⚡ Cache<br/>[Redis/etc]"]
+
+    Client --> CDN
+    CDN --> FE
+    CDN --> BE
+    BE --> DB
+    BE --> Cache
+```
+
+## Componentes Principales
+
+### Frontend
+
+- **Framework**: [Ej: React 18 / Next.js 14 / Vue 3]
+- **Renderizado**: [SSR / SSG / SPA / Híbrido]
+- **Estado**: [Local state / Context / Zustand / Redux]
+- **Routing**: [Client-side / Server-side / File-based]
+- **Estilos**: [Tailwind / CSS Modules / Styled Components]
+
+> Ver ADRs relevantes en `docs/adr/` para entender por qué se eligió cada tecnología.
+
+### Backend / API
+
+- **Framework**: [Ej: Express / Fastify / NestJS / Hono]
+- **Arquitectura**: [Monolito / Microservicios / Serverless]
+- **Autenticación**: [JWT / Session / OAuth / API Keys]
+- **Validación**: [Zod / Joi / class-validator]
+
+### Base de Datos
+
+- **Tipo**: [Relacional / NoSQL / Híbrido]
+- **Motor**: [PostgreSQL / MySQL / MongoDB]
+- **ORM**: [Prisma / TypeORM / Sequelize / Drizzle]
+- **Migraciones**: [Gestionadas por el ORM / Manuales]
+
+## Flujos Principales
+
+### Flujo de Autenticación
+
+```mermaid
+sequenceDiagram
+    participant U as Usuario
+    participant FE as Frontend
+    participant BE as Backend
+    participant DB as Base de datos
+
+    U->>FE: Login (email + password)
+    FE->>BE: POST /auth/login
+    BE->>DB: Verificar credenciales
+    DB-->>BE: Usuario válido
+    BE-->>FE: JWT + Refresh Token
+    FE->>FE: Almacenar tokens
+    U->>FE: Acción protegida
+    FE->>BE: Request + Bearer token
+    BE->>BE: Verificar JWT
+    BE-->>FE: Respuesta
+```
+
+### Flujo de Datos Principal
+
+```mermaid
+sequenceDiagram
+    participant U as Usuario
+    participant FE as Frontend
+    participant BE as Backend
+    participant DB as Base de datos
+
+    U->>FE: Acción en UI
+    FE->>BE: API Request
+    BE->>BE: Validación + Lógica
+    BE->>DB: Read/Write
+    DB-->>BE: Resultado
+    BE-->>FE: Respuesta JSON
+    FE->>FE: Actualizar UI
+    FE-->>U: Vista actualizada
+```
+
+## Decisiones Arquitectónicas Clave
+
+Las decisiones técnicas importantes están documentadas como ADRs en `docs/adr/`. Aquí un resumen:
+
+| Decisión | ADR | Resumen |
+|----------|-----|---------|
+| [Ej: Base de datos] | `0002-*` | [Por qué se eligió] |
+| [Ej: Framework frontend] | `0003-*` | [Por qué se eligió] |
+| [Ej: Autenticación] | `0004-*` | [Por qué se eligió] |
+
+> **Nota**: Para criterios de cuándo crear un ADR, ver [`docs/adr/TEMPLATE.md`](../adr/TEMPLATE.md).
+
+## Límites del Sistema
+
+### Qué NO hace este sistema
+
+- [Limitación 1]
+- [Limitación 2]
+
+### Escalabilidad
+
+- **Horizontal**: [Cómo escala el backend]
+- **Vertical**: [Límites de recursos]
+- **BD**: [Estrategia de escalado de datos]
+
+## Dependencias Externas
+
+| Servicio | Propósito | Alternativa si cae |
+|----------|-----------|-------------------|
+| [Servicio 1] | [Qué hace] | [Plan B] |
+| [Servicio 2] | [Qué hace] | [Plan B] |
+
+## Diagramas Relacionados
+
+- Ver [`docs/internal/agent-guide.md`](../internal/agent-guide.md) para diagramas de flujo de agentes
+- Ver `docs/guides/runbooks/` para procedimientos operativos
+- Ver `docs/reference/infrastructure.md` para detalles de entornos
+- Ver `docs/reference/api.md` para la referencia de la API

package/templates/modules/guides/docs/guides/deployment.md

@@ -0,0 +1,189 @@
+---
+created: "2025-01-01"
+status: active
+type: guide
+tags: [guía, deployment, deploy, producción, staging]
+---
+
+# Guía de Deployment
+
+Instrucciones paso a paso para hacer deploy de la aplicación a cada entorno.
+
+---
+
+## Entornos
+
+| Entorno | Propósito | URL | Branch | Auto-deploy |
+|---------|-----------|-----|--------|-------------|
+| **Development** | Desarrollo local | `http://localhost:3000` | Cualquiera | N/A |
+| **Staging** | QA y validación antes de producción | `https://staging.[dominio]` | `develop` o `main` | Sí (push a branch) |
+| **Production** | Usuarios finales | `https://[dominio]` | `main` | Sí (tag / release) |
+
+Ver detalles de infraestructura en [`docs/reference/infrastructure.md`](../reference/infrastructure.md).
+
+---
+
+## Prerrequisitos
+
+- Acceso al repositorio con permisos de push a `main`.
+- Acceso a la plataforma de CI/CD (ej. {{TECH_STACK}}, Vercel, AWS Console).
+- Variables de entorno configuradas para el entorno destino (ver [`configuration.md`](../reference/configuration.md)).
+
+---
+
+## Deploy a Staging
+
+Staging se actualiza automáticamente al hacer push a `[develop / main]`. Si necesitas deploy manual:
+
+### Opción A: Deploy automático (recomendado)
+
+```bash
+# Hacer push a la branch que triggera staging
+git push origin [develop / main]
+```
+
+Verificar en la plataforma de CI/CD que el pipeline pasó correctamente.
+
+### Opción B: Deploy manual
+
+```bash
+# 1. Construir la aplicación
+[npm run build]
+
+# 2. Deploy manual (según plataforma)
+[comando de deploy específico — ej. vercel --prod, aws deploy push, etc.]
+```
+
+### Verificación post-deploy
+
+Después de que el deploy termine:
+
+1. Abrir `https://staging.[dominio]` y verificar que la versión es la correcta.
+2. Ejecutar smoke tests manuales:
+   - [ ] Login funciona
+   - [ ] Página principal carga
+   - [ ] [Flujo principal del negocio] funciona end-to-end
+3. Verificar que no hay errores en consola (browser) ni en logs (servidor).
+4. Verificar que la versión/metadata es correcta (footer, health check, etc.).
+
+---
+
+## Deploy a Producción
+
+**Importante**: Los deploys a producción se hacen desde `main` **únicamente**. Nunca desde branches de feature.
+
+### Pre-deploy checklist
+
+Antes de hacer deploy a producción, verificar:
+
+- [ ] Todos los tests pasan en CI (último build verde).
+- [ ] Staging fue validado por QA/producto.
+- [ ] No hay migraciones de base de datos pendientes (o están preparadas).
+- [ ] Las variables de entorno de producción están actualizadas.
+- [ ] El CHANGELOG está actualizado.
+- [ ] Se comunicó al equipo el horario del deploy (si aplica).
+
+### Proceso
+
+#### Opción A: Deploy automático via tag
+
+```bash
+# 1. Crear un tag de release
+git tag -a v[VERSIÓN] -m "Release v[VERSIÓN]"
+
+# 2. Pushear el tag
+git push origin v[VERSIÓN]
+
+# 3. El pipeline de CI/CD detecta el tag y hace deploy automático
+```
+
+#### Opción B: Deploy manual
+
+```bash
+# 1. Asegurarse de estar en main y actualizado
+git checkout main
+git pull origin main
+
+# 2. Construir
+[npm run build]
+
+# 3. Deploy
+[comando de deploy a producción]
+```
+
+### Post-deploy
+
+Inmediatamente después del deploy:
+
+1. **Verificar la URL de producción**: abrir `https://[dominio]` y confirmar que la versión es la nueva.
+2. **Smoke tests rápidos**:
+   - [ ] Página principal carga
+   - [ ] Login funciona
+   - [ ] [Flujo principal] funciona
+3. **Monitorear logs** durante los primeros 15 minutos:
+   - Verificar que no hay errores inusuales.
+   - Verificar que el tráfico se ve normal.
+4. **Actualizar CHANGELOG**: mover los cambios de "Sin publicar" a la sección de la versión.
+5. **Comunicar**: notificar al equipo que el deploy fue exitoso (Slack / Teams / email).
+
+### Rollback
+
+Si algo sale mal después del deploy:
+
+```bash
+# 1. Identificar la versión anterior (la que funcionaba)
+git log --oneline -5
+
+# 2. Re-deployear la versión anterior
+git checkout v[VERSIÓN_ANTERIOR]
+[comando de deploy a producción]
+
+# 3. Alternativa: revertir el merge commit
+git revert -m 1 [HASH_DEL_MERGE]
+git push origin main
+```
+
+---
+
+## Migraciones de base de datos
+
+Las migraciones se ejecutan como parte del pipeline de deploy, pero si necesitaras ejecutarlas manualmente:
+
+```bash
+# Ver el estado de las migraciones
+[comando de status — ej. npm run db:status]
+
+# Ejecutar migraciones pendientes
+[comando de migración — ej. npm run db:migrate]
+
+# Rollback de la última migración (solo en emergencias)
+[comando de rollback — ej. npm run db:rollback]
+```
+
+**Regla**: Las migraciones deben ser **siempre hacia adelante** (additive). No modificar columnas existentes en breaking ways. Crear nuevas columnas y migrar datos gradualmente.
+
+---
+
+## Variables de entorno por entorno
+
+| Variable | Development | Staging | Production |
+|----------|-------------|---------|------------|
+| `APP_ENV` | `development` | `staging` | `production` |
+| `DATABASE_URL` | Local | Staging DB | Production DB |
+| `API_KEY_[SERVICIO]` | Key de testing | Key de staging | Key de producción |
+| `LOG_LEVEL` | `debug` | `info` | `warn` |
+
+Ver la referencia completa en [`configuration.md`](../reference/configuration.md).
+
+---
+
+## Troubleshooting de deploys
+
+| Problema | Causa probable | Solución |
+|----------|---------------|----------|
+| Build falla en CI pero pasa local | Diferencia de versiones de Node/npm | Verificar que `.nvmrc` o `engines` en `package.json` coincida con CI |
+| Deploy exitoso pero página en blanco | Variables de entorno faltantes | Verificar todas las vars requeridas en el entorno |
+| Migración falla | Cambio breaking en schema | Ejecutar rollback y corregir la migración |
+| Timeout en deploy | Recursos insuficientes | Verificar logs del CI/CD y recursos del servidor |
+
+Más soluciones en [`troubleshooting.md`](troubleshooting.md).

package/templates/modules/guides/docs/guides/runbooks/TEMPLATE.md

@@ -0,0 +1,86 @@
+---
+created: "2026-05-07"
+updated: "2026-05-07"
+status: active
+type: how-to
+tags: [ops, runbooks, template]
+---
+
+# Template de Runbook
+
+> [!info] Cuándo crear un runbook
+> Crea un runbook cuando un proceso operativo se repite o cuando necesitas documentar pasos para resolver un incidente específico. Guárdalo en `docs/guides/runbooks/`.
+
+## Nombre del Runbook
+
+**Tipo**: [operativo | incidente | mantenimiento]
+**Severidad**: [baja | media | alta | crítica]
+**Frecuencia**: [diario | semanal | mensual | bajo demanda]
+
+## Contexto
+
+¿Qué es este proceso? ¿Por qué existe? ¿Cuándo se ejecuta?
+
+## Síntomas / Triggers
+
+¿Qué indica que hay que ejecutar este runbook?
+
+- Síntoma 1
+- Síntoma 2
+- Alerta de monitoring que lo dispara
+
+## Prerrequisitos
+
+- [ ] Acceso a [sistema/servidor]
+- [ ] Permisos de [rol]
+- [ ] Herramientas: [lista]
+
+## Pasos
+
+### Paso 1: [Título del paso]
+
+**Acción**: Descripción clara de qué hacer
+**Comando** (si aplica):
+```bash
+comando-aquí
+```
+**Verificación**: Cómo confirmar que el paso salió bien
+
+### Paso 2: [Título del paso]
+
+**Acción**: Descripción clara
+**Comando**:
+```bash
+siguiente-comando
+```
+**Verificación**: Qué esperar
+
+### Paso N: Verificación final
+
+Confirmar que el proceso se completó exitosamente:
+
+- [ ] Check 1
+- [ ] Check 2
+
+## Rollback
+
+Si algo sale mal, cómo revertir:
+
+1. Paso de rollback 1
+2. Paso de rollback 2
+
+## Escalación
+
+Si no puedes resolver:
+
+| Nivel   | Contacto             | Cuándo escalar                    |
+|---------|----------------------|------------------------------------|
+| L1      | [Equipo/dev]         | Si los pasos del runbook fallan    |
+| L2      | [Tech lead]          | Si el problema requiere acceso especial |
+| L3      | [CTO/Infra lead]     | Si hay riesgo de pérdida de datos  |
+
+## Notas
+
+- Cualquier consideración especial
+- Lecciones aprendidas de ejecuciones anteriores
+- Enlaces a ADRs o docs relacionados

package/templates/modules/guides/docs/guides/troubleshooting.md

@@ -0,0 +1,65 @@
+---
+created: "2026-05-07"
+updated: "2026-05-07"
+status: active
+type: how-to
+tags: [ops, troubleshooting, debugging]
+---
+
+# Troubleshooting
+
+Problemas comunes encontrados durante el desarrollo y sus soluciones.
+
+> [!tip] Cómo usar esta guía
+> Busca tu problema en la tabla o por las secciones. Si encuentras un problema nuevo y lo resuelves, añádelo aquí para que el próximo developer no pierda tiempo.
+
+## Problemas de Entorno
+
+| Problema | Causa probable | Solución |
+|----------|---------------|----------|
+| `npm install` falla con EACCES | Permisos de npm global | Usa `nvm` o reinstala Node con permisos correctos |
+| `command not found: node` | Node no instalado o no en PATH | Instala con `nvm install --lts` y reinicia terminal |
+| Puerto 3000 ocupado | Otro proceso usando el puerto | `lsof -i :3000` (macOS) o `netstat -ano | findstr :3000` (Windows) y mata el proceso |
+| Variables de entorno no cargadas | Falta archivo `.env` | Copia `.env.example` a `.env` y configura los valores |
+
+## Problemas de Build
+
+| Problema | Causa probable | Solución |
+|----------|---------------|----------|
+| Error de tipos TypeScript | Tipos incompatibles o faltantes | Ejecuta `[npm run typecheck]` para ver errores específicos |
+| Build falla en CI pero no local | Diferencia de entorno (Node version, deps) | Verifica que `.nvmrc` o `engines` en package.json coincida con CI |
+| Error "Module not found" | Dependencia no instalada o path incorrecto | `rm -rf node_modules && npm install` o verifica import paths |
+| Out of memory en build | Proyecto grande sin suficiente RAM | Aumenta memoria: `NODE_OPTIONS="--max-old-space-size=4096" npm run build` |
+
+## Problemas de Runtime
+
+| Problema | Causa probable | Solución |
+|----------|---------------|----------|
+| CORS error en API calls | Backend no configurado para el origen del frontend | Verifica configuración CORS en el backend |
+| 401 Unauthorized | Token expirado o no enviado | Verifica que el token se envía en headers y no ha expirado |
+| Pantalla blanca en producción | Error JS no capturado, assets no cargan | Revisa consola del navegador, verifica que los assets se deployaron |
+| Hydration mismatch (SSR) | HTML server != HTML client | Verifica que no haya `Date.now()`, `Math.random()` o APIs del navegador en SSR |
+
+## Problemas de Base de Datos
+
+| Problema | Causa probable | Solución |
+|----------|---------------|----------|
+| Connection refused | BD no arrancada o URL incorrecta | Verifica que el servicio esté corriendo y la URL en `.env` sea correcta |
+| Migration error | Migración pendiente o conflicto | Ejecuta migraciones pendientes o resetea la BD local |
+| Timeout en queries | Query ineficiente o locks | Revisa el query plan, añade índices si es necesario |
+
+## Problemas de Git
+
+| Problema | Causa probable | Solución |
+|----------|---------------|----------|
+| Merge conflict | Cambios en mismas líneas | Resuelve manualmente: busca `<<<<<<<`, elige el correcto, elimina marcadores |
+| `git push` rechazado | Branch remota tiene commits nuevos | `git pull --rebase origin <branch>` y resuelve conflictos si hay |
+| Hook pre-commit falla | Linting o formatting falla | Ejecuta `npm run lint:fix` y vuelve a commitear |
+
+## Cómo añadir nuevos problemas
+
+Cuando resuelvas un problema que no esté aquí:
+
+1. Añade una fila a la tabla correspondiente
+2. Incluye: problema, causa, solución
+3. Si la solución es compleja, crea un how-to separado en `docs/guides/` y enlázalo aquí

package/templates/modules/operations/docs/operations/README.md

@@ -0,0 +1,115 @@
+---
+created: "2026-05-07"
+updated: "2026-05-07"
+status: active
+type: how-to
+tags: [ops, operations, monitoring, incidents, production]
+---
+
+# Operaciones
+
+Centro de operaciones para el proyecto en producción.
+
+> [!warning] Solo para entornos con producción
+> Esta sección se crea cuando el proyecto tiene entorno de producción. Si el proyecto aún no está en producción, puedes ignorar esta sección.
+
+## Monitorización
+
+### Dashboards
+
+| Dashboard | URL | Qué monitoriza |
+|-----------|-----|----------------|
+| Principal | [URL] | Health checks, uptime, errores |
+| Rendimiento | [URL] | Latencia, throughput, recursos |
+| Business | [URL] | Métricas de negocio |
+
+### Alertas Configuradas
+
+| Alerta | Severidad | Umbral | Canal de notificación |
+|--------|-----------|--------|-----------------------|
+| Servicio caído | Crítica | Health check fail > 2 min | [Slack/Email/PagerDuty] |
+| Error rate alto | Alta | >5% de requests con error 5xx | [Slack/Email] |
+| Latencia alta | Media | p95 > 2 segundos | [Slack] |
+| Disco lleno | Alta | >90% uso de disco | [Slack/Email] |
+| Certificado SSL por expirar | Media | <30 días | [Email] |
+
+## SLAs y SLOs
+
+| Métrica | SLO | Ventana | Medición |
+|---------|-----|---------|----------|
+| Disponibilidad | 99.9% | 30 días | Uptime checks |
+| Latencia p95 | <500ms | 30 días | APM |
+| Latencia p99 | <2s | 30 días | APM |
+| Error rate | <0.1% | 7 días | Log aggregation |
+| Tiempo de respuesta API | <200ms | 30 días | Synthetic monitoring |
+
+## Gestión de Incidentes
+
+### Niveles de Severidad
+
+| Nivel | Definición | Ejemplo | Tiempo de respuesta |
+|-------|------------|---------|-------------------|
+| P0 - Crítico | Servicio completamente caído, afecta a todos los usuarios | Sitio no carga, BD inaccesible | <15 min |
+| P1 - Alto | Funcionalidad principal no funciona, afecta muchos usuarios | Login roto, checkout falla | <1 hora |
+| P2 - Medio | Funcionalidad secundaria afectada, workaround disponible | Búsqueda lenta, email no envía | <4 horas |
+| P3 - Bajo | Problema cosmético o menor | Typo, UI glitch | Próximo sprint |
+
+### Proceso de Incidente
+
+1. **Detección**: Alerta automática o reporte de usuario
+2. **Triage**: Asignar severidad y responsable
+3. **Comunicación**: Notificar al equipo en canal de incidencias
+4. **Resolución**: Diagnosticar, aplicar fix, verificar
+5. **Post-mortem**: Documentar qué pasó, por qué, y cómo prevenirlo
+
+### Plantilla de Post-mortem
+
+Guardar en `docs/operations/post-mortems/YYYY-MM-DD-titulo.md`:
+
+```markdown
+## Resumen
+[1-2 oraciones: qué pasó, impacto, duración]
+
+## Timeline
+- HH:MM - Detección
+- HH:MM - Investigación empieza
+- HH:MM - Causa raíz identificada
+- HH:MM - Fix aplicado
+- HH:MM - Servicio restaurado
+
+## Causa Raíz
+[Qué causó el incidente, no qué síntomas se vieron]
+
+## Impacto
+- Duración: X horas/minutos
+- Usuarios afectados: X
+- Datos perdidos: Sí/No
+
+## Acciones Preventivas
+- [ ] Acción 1 — Responsable — Fecha límite
+- [ ] Acción 2 — Responsable — Fecha límite
+
+## Lecciones Aprendidas
+[Qué aprendimos que cambie cómo trabajamos]
+```
+
+## Backups
+
+| Recurso | Frecuencia | Retención | Ubicación |
+|---------|-----------|-----------|-----------|
+| Base de datos | Diaria | 30 días | [Proveedor/Ubicación] |
+| Assets estáticos | En cada deploy | Últimos 10 deploys | [CDN/Storage] |
+| Configuración | Versionada en git | Completa | Repositorio |
+
+## On-Call
+
+Si el proyecto tiene rotación de on-call:
+
+| Día | Responsable | Horario | Contacto |
+|-----|-------------|---------|----------|
+| Lunes | [Nombre] | 9:00 - 18:00 | [Canal contacto] |
+| ... | ... | ... | ... |
+
+## Runbooks Relacionados
+
+Los runbooks operativos están en `docs/guides/runbooks/`. Cada uno documenta un procedimiento específico para resolver problemas o realizar tareas operativas.

package/templates/modules/product/docs/product/overview.md

@@ -0,0 +1,90 @@
+---
+created: "2025-01-01"
+status: active
+type: product-context
+tags: [producto, visión, negocio, stakeholders, métricas]
+---
+
+# Visión del Producto
+
+## Qué es
+
+{{PROJECT_NAME}} es [descripción de una oración: qué tipo de producto es y para qué sirve]. Es un proyecto de tipo [web app / landing / portal / plataforma] orientado a [segmento: corporativo / B2B / B2C / interno].
+
+## Por qué existe
+
+**Problema que resuelve**: [Describir el problema o necesidad que motivó la creación del proyecto. ¿Qué hacía el cliente/equipo antes? ¿Qué fricción existía?]
+
+**Oportunidad**: [Por qué ahora. Qué cambió en el mercado, la organización o la tecnología que hace que este proyecto tenga sentido en este momento.]
+
+## Usuarios objetivo
+
+| Perfil | Quién es | Necesidad principal | Frecuencia de uso |
+|--------|----------|--------------------|--------------------|
+| **[Usuario primario]** | [Descripción: rol, contexto, nivel técnico] | [Qué viene a hacer al sistema. La tarea #1.] | [Diaria / Semanal / Mensual] |
+| **[Usuario secundario]** | [Descripción] | [Qué viene a hacer] | [Frecuencia] |
+| **[Usuario administrador]** | [Descripción] | [Gestionar configuración, usuarios, datos maestros] | [Frecuencia] |
+
+## Valor que aporta
+
+Para cada perfil de usuario:
+
+| Usuario | Antes (sin el proyecto) | Después (con el proyecto) | Medible en |
+|---------|------------------------|--------------------------|-----------|
+| **[Perfil 1]** | [Cómo resolvía el problema antes — manual, Excel, otro sistema] | [Cómo lo resuelve ahora — automatizado, centralizado, más rápido] | [Métrica: tiempo, errores, costos] |
+| **[Perfil 2]** | [Situación anterior] | [Situación nueva] | [Métrica] |
+
+## Stakeholders
+
+| Nombre / Rol | Responsabilidad en el proyecto | Decisiones que aprueba | Contacto |
+|-------------|-------------------------------|----------------------|----------|
+| **[Product Owner]** | Define prioridades y acepta entregas | Features, alcance, release dates | [email / slack] |
+| **[Tech Lead]** | Guía decisiones técnicas | Arquitectura, stack, deuda técnica | [email / slack] |
+| **[Diseñador/a]** | Define la experiencia visual y de interacción | UI/UX, design system, flujos | [email / slack] |
+| **[Stakeholder de negocio]** | Representa las necesidades del cliente final | Funcionalidad de negocio, priorización | [email / slack] |
+
+## Métricas de éxito
+
+### Métricas primarias (KPIs)
+
+| Métrica | Objetivo | Medición | Frecuencia |
+|---------|----------|----------|------------|
+| **[Métrica 1 — ej. Tasa de adopción]** | [Valor objetivo — ej. 80% de usuarios activos en 3 meses] | [Cómo se mide — ej. analytics de login] | [Mensual] |
+| **[Métrica 2 — ej. Tiempo de tarea]** | [Valor objetivo — ej. reducir de 30min a 5min] | [Cómo se mide] | [Semanal] |
+
+### Métricas de calidad
+
+| Métrica | Objetivo | Medición |
+|---------|----------|----------|
+| **Uptime** | 99.9% | Monitoreo de infraestructura |
+| **Tiempo de carga (LCP)** | < 2.5s | Lighthouse / Web Vitals |
+| **Errores en producción** | < 0.1% de requests | Error tracking (Sentry, etc.) |
+| **Cobertura de tests** | > 80% | CI/CD pipeline |
+
+### Métricas de satisfacción
+
+| Métrica | Objetivo | Medición |
+|---------|----------|----------|
+| **NPS / CSAT** | [Valor] | [Encuesta / feedback in-app] |
+| **Tickets de soporte** | Reducir X% vs. sistema anterior | Help desk |
+
+---
+
+## Contexto regulatorio y restricciones
+
+- **Privacidad**: [Indicar si aplica GDPR, LFPDPPP, etc. Qué datos personales se manejan.]
+- **Accesibilidad**: Nivel WCAG 2.1 AA como mínimo.
+- **Seguridad**: [Normas de seguridad corporativas. Ej. OWASP Top 10, pen testing anual.]
+- **Compliance**: [Otras restricciones del sector — ej. PCI DSS para pagos, SOC 2 para SaaS.]
+
+---
+
+## Evolución esperada
+
+Este producto está pensado para crecer en las siguientes direcciones:
+
+1. **Corto plazo (0-3 meses)**: [MVP o versión inicial con funcionalidad core.]
+2. **Mediano plazo (3-6 meses)**: [Features complementarias, integraciones.]
+3. **Largo plazo (6-12 meses)**: [Escalabilidad, nuevos módulos, expansión.]
+
+Ver el detalle de features planificados en [`docs/roadmap.md`](../roadmap.md).