# MAPEO Y SEPARACION DE DIRECTIVAS: GENERALES vs ESPECIFICAS

**Fecha:** 2025-12-05
**Proposito:** Documentar la separacion correcta entre directivas globales (core) y especificas (por proyecto)

---

## PRINCIPIO DE SEPARACION

```
┌─────────────────────────────────────────────────────────────────────────┐
│                    DIRECTIVAS GLOBALES (core/orchestration/)            │
│  • Aplican a TODOS los proyectos                                         │
│  • NO mencionan proyecto especifico                                      │
│  • Usan PLACEHOLDERS para paths: {PROJECT}, {PROJECT_ROOT}, etc.        │
│  • Definen QUE hacer (principios, estandares, flujos)                   │
└─────────────────────────────────────────────────────────────────────────┘
                               │
                               ▼ HEREDAN
┌─────────────────────────────────────────────────────────────────────────┐
│           DIRECTIVAS ESPECIFICAS (projects/{proyecto}/orchestration/)    │
│  • Aplican SOLO al proyecto especifico                                   │
│  • PUEDEN sobrescribir directivas globales                              │
│  • Definen paths concretos, schemas, configuraciones del proyecto       │
│  • Referencian docs/ y apps/ del proyecto                               │
└─────────────────────────────────────────────────────────────────────────┘
```

---

## ANALISIS: DIRECTIVAS DEL PROYECTO GAMILIT ORIGINAL

### Ubicacion original:
`/home/isem/workspace-old/wsl-ubuntu/workspace/workspace-gamilit/gamilit/projects/gamilit/orchestration/directivas/`

### Directivas encontradas:

| Archivo | Tipo | Accion Requerida |
|---------|------|------------------|
| `DIRECTIVA-POLITICA-CARGA-LIMPIA.md` | **GENERALIZABLE** | Convertir a general con placeholders |
| `DIRECTIVA-DISENO-BASE-DATOS.md` | **MIXTO** | Separar: diseño general vs schemas especificos |
| `DIRECTIVA-CONTROL-VERSIONES.md` | **GENERAL** | Ya es general |
| `DIRECTIVA-CALIDAD-CODIGO.md` | **GENERAL** | Ya es general |
| `DIRECTIVA-DOCUMENTACION-OBLIGATORIA.md` | **GENERAL** | Ya es general |
| `DIRECTIVA-FLUJO-5-FASES.md` | **GENERAL** | Ya es general |
| `DIRECTIVA-VALIDACION-SUBAGENTES.md` | **GENERAL** | Ya es general |
| `DIRECTIVA-GESTION-BACKUPS-GITIGNORE.md` | **GENERAL** | Ya es general |
| `POLITICAS-USO-AGENTES.md` | **GENERAL** | Ya es general |
| `PROTOCOLO-ESCALAMIENTO-PO.md` | **GENERAL** | Ya es general |
| `ESTANDARES-NOMENCLATURA.md` | **GENERAL** | Ya es general (base) |
| `SISTEMA-RETROALIMENTACION-MEJORA-CONTINUA.md` | **GENERAL** | Ya es general |
| `ESTANDARES-API-ROUTES.md` | **ESPECIFICO** | Mantener en gamilit |
| `ESTANDARES-TESTING-API.md` | **ESPECIFICO** | Mantener en gamilit |
| `AUTOMATIZACION-VALIDACION-RUTAS.md` | **ESPECIFICO** | Mantener en gamilit |
| `PITFALLS-API-ROUTES.md` | **ESPECIFICO** | Mantener en gamilit |
| `GUIA-NOMENCLATURA-COMPLETA.md` | **ESPECIFICO** | Mantener en gamilit (extiende base) |
| `CHECKLIST-REFACTORIZACION.md` | **GENERAL** | Mover a core/checklists |
| `CHECKLIST-CODE-REVIEW-API.md` | **GENERAL** | Mover a core/checklists |

---

## DIRECTIVAS GLOBALES: ESTRUCTURA REQUERIDA

### core/orchestration/directivas/ (GENERALES)

```yaml
Directivas de Flujo y Proceso:
  - DIRECTIVA-FLUJO-5-FASES.md           # Workflow obligatorio
  - DIRECTIVA-VALIDACION-SUBAGENTES.md   # Validacion de entregables
  - POLITICAS-USO-AGENTES.md             # Reglas de delegacion

Directivas de Calidad:
  - DIRECTIVA-CALIDAD-CODIGO.md          # Estandares de codigo
  - DIRECTIVA-DOCUMENTACION-OBLIGATORIA.md
  - DIRECTIVA-CONTROL-VERSIONES.md       # Git, commits, branches
  - DIRECTIVA-GESTION-BACKUPS-GITIGNORE.md

Directivas de Base de Datos:
  - DIRECTIVA-DISENO-BASE-DATOS-BASE.md  # <- NUEVO: Principios generales
  - DIRECTIVA-POLITICA-CARGA-LIMPIA-BASE.md  # <- NUEVO: Politica sin paths

Directivas de Retroalimentacion:
  - SISTEMA-RETROALIMENTACION.md
  - PROTOCOLO-ESCALAMIENTO-PO.md

Estandares Base:
  - ESTANDARES-NOMENCLATURA-BASE.md      # Nomenclatura general
```

### Checklists Globales (core/orchestration/checklists/)

```yaml
  - CHECKLIST-CODE-REVIEW-BASE.md        # Review general
  - CHECKLIST-REFACTORIZACION.md
```

---

## DIRECTIVAS ESPECIFICAS GAMILIT: ESTRUCTURA REQUERIDA

### projects/gamilit/orchestration/directivas/

```yaml
Base de Datos (extiende/sobrescribe core):
  - DIRECTIVA-DISENO-BASE-DATOS.md       # Schemas especificos de gamilit
  - DIRECTIVA-POLITICA-CARGA-LIMPIA.md   # Paths especificos de gamilit

API (especifico de gamilit):
  - ESTANDARES-API-ROUTES.md             # Convenciones API gamilit
  - ESTANDARES-TESTING-API.md            # Testing API gamilit
  - AUTOMATIZACION-VALIDACION-RUTAS.md   # Validacion rutas gamilit
  - PITFALLS-API-ROUTES.md               # Errores comunes gamilit

Nomenclatura (extiende core):
  - GUIA-NOMENCLATURA-COMPLETA.md        # Nomenclatura completa gamilit
```

---

## EJEMPLO: SEPARACION DE DIRECTIVA-POLITICA-CARGA-LIMPIA

### VERSION GLOBAL (core/orchestration/directivas/)

```markdown
# DIRECTIVA: POLITICA DE CARGA LIMPIA (Clean Load Policy)

**Ambito:** Todos los proyectos del workspace
**Tipo:** Directiva Obligatoria
**Stack:** PostgreSQL 15+

## PROPOSITO
Garantizar que la base de datos pueda recrearse desde archivos DDL...

## PATHS (usar variables de proyecto)
- DDL: `{PROJECT_ROOT}/apps/database/ddl/schemas/{schema}/`
- Scripts: `{PROJECT_ROOT}/apps/database/`
- Recreacion: `./{PROJECT_ROOT}/apps/database/drop-and-recreate-database.sh`

## REGLAS OBLIGATORIAS
1. DDL-First Approach
2. Prohibicion de Migrations
3. Prohibicion de Fixes y Patches
...
```

### VERSION ESPECIFICA GAMILIT (projects/gamilit/orchestration/directivas/)

```markdown
# DIRECTIVA: POLITICA DE CARGA LIMPIA - GAMILIT

**Proyecto:** GAMILIT - Sistema de Gamificacion Educativa
**Extiende:** core/orchestration/directivas/DIRECTIVA-POLITICA-CARGA-LIMPIA-BASE.md

## PATHS ESPECIFICOS GAMILIT
- DDL: `apps/database/ddl/schemas/gamilit/`
- Scripts: `apps/database/`
- Recreacion: `./apps/database/drop-and-recreate-database.sh`
- DB Name: `gamilit_platform`

## SCHEMAS ESPECIFICOS
- auth_management
- academic_management
- gamification_system
- exercise_management
- progress_tracking
- guild_management
- notification_management
...
```

---

## EJEMPLO: SEPARACION DE DIRECTIVA-DISENO-BASE-DATOS

### VERSION GLOBAL (core/orchestration/directivas/)

```markdown
# DIRECTIVA: DISENO DE BASE DE DATOS Y NORMALIZACION

**Ambito:** Todos los proyectos del workspace
**Stack:** PostgreSQL 15+

## PROPOSITO
Establecer criterios de diseno de base de datos...

## NIVELES DE NORMALIZACION
[Principios 1NF, 2NF, 3NF - SIN ejemplos especificos de proyecto]

## CLAVES Y CONSTRAINTS
[Nomenclatura general: fk_{tabla}_to_{destino}, chk_{tabla}_{col}]

## INDEXACION ESTRATEGICA
[Reglas generales de cuando indexar]

## AUDITORÌA
[Columnas estandar: created_at, updated_at, etc.]
```

### VERSION ESPECIFICA GAMILIT (projects/gamilit/orchestration/directivas/)

```markdown
# DIRECTIVA: DISENO DE BASE DE DATOS - GAMILIT

**Proyecto:** GAMILIT - Sistema de Gamificacion Educativa
**Extiende:** core/orchestration/directivas/DIRECTIVA-DISENO-BASE-DATOS-BASE.md

## SCHEMAS DE GAMILIT
- auth_management: Usuarios, roles, permisos, tenants
- academic_management: Instituciones, cursos, estudiantes
- gamification_system: Puntos, niveles, badges, challenges
- exercise_management: Ejercicios, tipos, soluciones
- progress_tracking: Progreso estudiantil, estadisticas
- guild_management: Guildas, rankings
- notification_management: Notificaciones, alertas

## EJEMPLOS ESPECIFICOS
[CREATE TABLE gamification_system.challenges ...]
[Vistas materializadas del proyecto]
```

---

## ACCIONES REQUERIDAS

### 1. Actualizar core/orchestration/directivas/

- [ ] **DIRECTIVA-DISENO-BASE-DATOS.md**: Remover menciones a "GAMILIT", schemas especificos. Usar placeholders.
- [ ] **Crear DIRECTIVA-POLITICA-CARGA-LIMPIA-BASE.md**: Version general sin paths especificos (actualmente no existe en core).

### 2. Actualizar projects/gamilit/orchestration/directivas/

- [ ] **DIRECTIVA-DISENO-BASE-DATOS.md**: Agregar header que indica que extiende core, especificar schemas de gamilit
- [ ] **DIRECTIVA-POLITICA-CARGA-LIMPIA.md**: Verificar paths, agregar DB name y schemas especificos

### 3. Crear documento de contexto de proyecto

- [ ] **projects/gamilit/orchestration/00-guidelines/CONTEXTO-PROYECTO.md**:
  - Stack tecnico
  - Schemas
  - Paths importantes
  - Variables a usar en directivas

---

## PLACEHOLDERS ESTANDAR PARA DIRECTIVAS GLOBALES

```yaml
Variables de Proyecto:
  {PROJECT}:         Nombre del proyecto (ej: gamilit, erp-suite)
  {PROJECT_ROOT}:    projects/{PROJECT}
  {APPS_ROOT}:       projects/{PROJECT}/apps
  {DOCS_ROOT}:       projects/{PROJECT}/docs
  {ORCHESTRATION}:   projects/{PROJECT}/orchestration

Variables de Base de Datos:
  {DB_NAME}:         Nombre de la base de datos
  {DB_DDL_PATH}:     {APPS_ROOT}/database/ddl
  {DB_SCRIPTS_PATH}: {APPS_ROOT}/database/scripts
  {DB_SEEDS_PATH}:   {APPS_ROOT}/database/seeds

Variables de Backend:
  {BACKEND_SRC}:     {APPS_ROOT}/backend/src
  {BACKEND_TESTS}:   {APPS_ROOT}/backend/tests

Variables de Frontend:
  {FRONTEND_SRC}:    {APPS_ROOT}/frontend/src
```

---

## REFERENCIA: HERENCIA DE DIRECTIVAS

Cuando un subagente trabaja en un proyecto:

1. **Lee directivas globales** de `core/orchestration/directivas/`
2. **Lee directivas especificas** de `projects/{proyecto}/orchestration/directivas/`
3. **En caso de conflicto**: La directiva especifica tiene precedencia
4. **Resuelve placeholders** usando `CONTEXTO-PROYECTO.md` del proyecto

---

**Documento creado:** 2025-12-05
**Siguiente paso:** Implementar las actualizaciones documentadas
