workspace-v1/orchestration/directivas/simco/SIMCO-CONTRIBUIR-CATALOGO.md

SIMCO: CONTRIBUIR AL CATÁLOGO

Versión: 1.0.0 Fecha: 2025-12-08 Aplica a: TODO agente que implemente funcionalidad reutilizable Prioridad: RECOMENDADA - Después de completar funcionalidad exitosamente

---

RESUMEN EJECUTIVO

Cuando implementes una funcionalidad común y reutilizable (auth, notificaciones, pagos, etc.) que funcione en producción, EVALÚA si debe agregarse al catálogo para beneficio de futuros proyectos.

---

PRINCIPIO FUNDAMENTAL

╔══════════════════════════════════════════════════════════════════════════════╗
║                                                                               ║
║           EL CATÁLOGO CRECE CON CADA PROYECTO EXITOSO                        ║
║                                                                               ║
║  "Documentar mientras desarrollas es más fácil que después."                 ║
║  "Código que no se documenta, no se reutiliza."                              ║
║                                                                               ║
╚══════════════════════════════════════════════════════════════════════════════╝

---

CUÁNDO APLICAR ESTA DIRECTIVA

Una funcionalidad ES candidata para el catálogo si cumple TODOS:

Criterio	Pregunta a Responder
Probada	¿Funciona en producción (al menos 1 proyecto)?
Reutilizable	¿NO es específica de un dominio de negocio?
Común	¿Se necesita en múltiples proyectos típicamente?
Compleja	¿Tiene suficiente complejidad que justifica documentar?
Estable	¿La API/estructura no cambia frecuentemente?

Ejemplos de funcionalidades candidatas:

• Autenticación, sesiones, rate limiting
• Notificaciones (email, push, in-app)
• Pagos, suscripciones
• WebSockets, real-time
• Multi-tenancy, feature flags
• File upload, image processing
• Audit logs, activity tracking
• Caching strategies

Ejemplos que NO van al catálogo:

• Lógica de negocio específica (cálculo de comisiones de trading)
• UI components específicos de un proyecto
• Configuraciones específicas de un proyecto
• Integraciones one-off con terceros

---

CHECKLIST RÁPIDO

EVALUAR CANDIDATURA
├── [ ] 1. ¿Cumple los 5 criterios de arriba?
├── [ ] 2. ¿El código está limpio y documentado?
└── [ ] 3. ¿Hay tests que validen el funcionamiento?

SI ES CANDIDATO → CONTRIBUIR
├── [ ] 4. Crear estructura en shared/catalog/{nombre}/
├── [ ] 5. Documentar README.md (descripción, trade-offs)
├── [ ] 6. Documentar IMPLEMENTATION.md (pasos)
├── [ ] 7. Actualizar CATALOG-INDEX.yml
├── [ ] 8. Actualizar @CATALOG README.md
├── [ ] 9. Actualizar ALIASES.yml
└── [ ] 10. Verificar que es encontrable por keywords

---

PROCESO DETALLADO

Paso 1: Preparar Estructura

# Crear directorio para la funcionalidad
mkdir -p shared/catalog/{nombre-en-kebab-case}/

# Crear archivos base
touch shared/catalog/{nombre}/README.md
touch shared/catalog/{nombre}/IMPLEMENTATION.md

Convención de nombres:

• Usar kebab-case: audit-logs, file-upload, caching-strategy
• Nombre descriptivo pero conciso

Paso 2: Documentar README.md

Estructura obligatoria:

# {Nombre de la Funcionalidad}

**Versión:** 1.0.0
**Origen:** projects/{proyecto-origen}
**Estado:** Production-Ready | Documentando
**Última actualización:** YYYY-MM-DD

---

## Descripción

{Descripción clara de qué hace y para qué sirve}

---

## Características

| Característica | Descripción |
|----------------|-------------|
| ... | ... |

---

## Stack Tecnológico

```yaml
backend:
  framework: NestJS
  # ...

---

Dependencias NPM

{
  "paquete": "^version"
}

---

Tablas Requeridas

Tabla	Propósito
...	...

---

Endpoints Principales

Método	Ruta	Descripción
...	...	...

---

Mantenido por: Sistema NEXUS Proyecto origen: {Proyecto}

### Paso 3: Documentar IMPLEMENTATION.md

**Estructura obligatoria:**

```markdown
# Guía de Implementación: {Nombre}

**Versión:** 1.0.0
**Complejidad:** Baja | Media | Alta

---

## Pre-requisitos

- [ ] Requisito 1
- [ ] Requisito 2

---

## Paso 1: {Nombre del Paso}

{Descripción}

```typescript
// Código de ejemplo

---

Variables de Entorno

VARIABLE=valor

---

Checklist de Implementación

• Paso completado 1
• Paso completado 2
• Build pasa sin errores
• Tests pasan

---

Troubleshooting

Error: "{mensaje}"

{Solución}

---

Versión: 1.0.0 Sistema: SIMCO Catálogo

### Paso 4: Actualizar CATALOG-INDEX.yml

```yaml
# Agregar bajo funcionalidades:
  {nombre}:
    nombre: "{Nombre Legible}"
    path: "shared/catalog/{nombre}/"
    alias: "@CATALOG_{ALIAS}"
    estado: "production-ready"
    origen: "projects/{proyecto}"
    version: "1.0.0"
    stack:
      - "NestJS"
      - "{otras tecnologías}"
    keywords:
      - "{keyword1}"
      - "{keyword2}"
      - "{keyword3}"
    caracteristicas:
      - "{característica 1}"
      - "{característica 2}"
    dependencias_npm:
      - "{paquete}"
    tablas_requeridas:
      - "{schema}.{tabla}"

IMPORTANTE: Las keywords son críticas para que la funcionalidad sea encontrable por grep.

Paso 5: Actualizar shared/catalog/README.md

Agregar fila en la tabla de "Estado Actual":

| {nombre} | 🟢 Production-Ready | {Origen} | {Stack Principal} |

Paso 6: Actualizar ALIASES.yml

# Agregar en sección de catálogo
@CATALOG_{ALIAS}: "shared/catalog/{nombre}/"

Paso 7: Validar

# Verificar que grep encuentra la funcionalidad
grep -i "{keyword}" shared/catalog/CATALOG-INDEX.yml

# Verificar estructura completa
ls -la shared/catalog/{nombre}/
# Debe mostrar: README.md, IMPLEMENTATION.md

# Verificar alias en documentación
grep "@CATALOG_{ALIAS}" shared/catalog/README.md

---

MANTENIMIENTO DEL CATÁLOGO

Actualizar Funcionalidad Existente

Cuando el código mejore en un proyecto:

1. ¿El cambio es generalizable (beneficia a todos)?
   - SÍ → Actualizar catálogo
   - NO → Mantener como adaptación local

2. Si actualizar:
   - Modificar IMPLEMENTATION.md con nuevos pasos
   - Incrementar versión en README.md
   - Actualizar CATALOG-INDEX.yml (version, caracteristicas)
   - Documentar cambio en historial

Deprecar Funcionalidad

Si una funcionalidad ya no es recomendada:

1. Marcar estado como "⚠️ Deprecated" en:
   - README.md de la funcionalidad
   - CATALOG-INDEX.yml (estado: "deprecated")
   - shared/catalog/README.md (tabla de estado)

2. Documentar:
   - Razón de deprecación
   - Alternativa recomendada

3. NO eliminar inmediatamente
   - Mantener por al menos 2 versiones mayores del catálogo

---

QUÉ NO HACER

❌ NO agregar funcionalidad sin tests
   → El catálogo es para código PROBADO

❌ NO documentar a medias
   → README incompleto = nadie lo usará

❌ NO olvidar actualizar CATALOG-INDEX.yml
   → Sin index, la funcionalidad no es encontrable

❌ NO usar código específico de negocio
   → Solo funcionalidades técnicas genéricas

❌ NO copiar código con secretos/credenciales
   → Usar variables de entorno siempre

---

INTEGRACIÓN CON DIRECTIVAS SIMCO

Esta directiva se integra con:

Directiva	Relación
@REUTILIZAR	Consultar catálogo ANTES de implementar
@CREAR	Si no existe en catálogo, crear nuevo
@DOCUMENTAR	Documentar también para posible contribución
@VALIDAR	Todo código de catálogo debe pasar build/lint

---

REFERENCIAS

• Catálogo completo: @CATALOG (shared/catalog/)
• Índice de búsqueda: @CATALOG_INDEX
• Para reutilizar: @REUTILIZAR (SIMCO-REUTILIZAR.md)
• Alias disponibles: @ALIASES (core/orchestration/referencias/ALIASES.yml)

---

Versión: 1.0.0 | Sistema: SIMCO | Mantenido por: Tech Lead