---
id: PROMPT-SA-15
agent_id: SA-15
model: claude-sonnet-4.5
type: General background
fase: FASE-5
scope: DDL-to-OQI coherence validation
mode: read-only
created: 2026-02-06
---

# PROMPT-SA-15: Validación Coherencia DDL-to-OQI

## Contexto

Eres un agente validador de coherencia documental. Tu tarea es verificar que los **documentos OQI reflejen correctamente la estructura DDL real** del proyecto.

**Proyecto:** trading-platform
**Objetivo:** Validar coherencia entre archivos `.sql` en `database/schemas/` y documentación en `docs/modulos-negocio/definitions/OQI-XXX/`

**FASE:** FASE-5 (Validation - read only)

## Instrucciones

### PASO 1: Inventariar schemas DDL reales

1. **Listar todos los archivos DDL:**
   - Usar Glob: `database/schemas/*.sql`
   - Identificar todos los schemas (esperados: 11 schemas)

2. **Para cada archivo .sql:**
   - Contar `CREATE TABLE` statements usando Grep
   - Extraer nombres de schemas (buscar `CREATE SCHEMA` o inferir de nombres de archivo)
   - Listar nombres de tablas principales

3. **Generar tabla de inventario DDL:**
   ```
   | Schema | Archivo | Tablas Count | Tablas Principales |
   |--------|---------|--------------|-------------------|
   | auth | 01-auth.sql | 12 | users, roles, permissions, sessions, ... |
   | trading | 05-trading.sql | 18 | orders, positions, trades, ... |
   | [etc.] | | | |
   ```

### PASO 2: Inventariar OQIs documentados

1. **Listar todos los OQI READMEs:**
   - Usar Glob: `docs/modulos-negocio/definitions/OQI-*/README.md`
   - Contar total de OQIs (esperados: 11)

2. **Para cada OQI README:**
   - Leer sección "Schemas DDL Asignados" (si existe)
   - Extraer qué schemas DDL dice que gestiona
   - Extraer conteo de tablas documentado

3. **Generar tabla de inventario OQI:**
   ```
   | OQI | Nombre | Schemas DDL Documentados | Tablas Documentadas |
   |-----|--------|-------------------------|---------------------|
   | OQI-001 | Auth | auth | 12 |
   | OQI-002 | Trading | trading, portfolio | 18, 8 |
   | [etc.] | | | |
   ```

### PASO 3: Cross-validation

1. **Comparar conteos de tablas:**
   - Para cada schema, comparar:
     - Tablas REALES en .sql (contadas en PASO 1)
     - Tablas DOCUMENTADAS en OQI (extraídas en PASO 2)
   - Identificar discrepancias

2. **Verificar cobertura:**
   - ¿Todos los schemas DDL están asignados a algún OQI?
   - ¿Hay schemas huérfanos (sin OQI)?
   - ¿Hay duplicación (un schema en múltiples OQIs)?

3. **Verificar completitud de documentación:**
   - ¿Todos los OQIs tienen sección "Schemas DDL Asignados"?
   - ¿Las descripciones de tablas son correctas?

### PASO 4: Generar reporte de coherencia

**Estructura del reporte:**

```markdown
# Reporte de Coherencia DDL ↔ OQI

## Resumen Ejecutivo
- **Total schemas DDL:** 11
- **Total OQIs:** 11
- **Schemas documentados:** X/11 (XX%)
- **Schemas sin asignar:** X
- **Discrepancias en conteos:** X

## Inventario DDL Real

| Schema | Archivo | Tablas | Funciones | Triggers | Enums |
|--------|---------|--------|-----------|----------|-------|
| auth | 01-auth.sql | 12 | 5 | 8 | 3 |
| trading | 05-trading.sql | 18 | 12 | 15 | 5 |
| [completar para 11 schemas] | | | | | |

**Total:** 101 tablas, 36 funciones, 46 triggers, 42 enums

## Inventario OQI Documentado

| OQI | Schemas Asignados | Tablas Documentadas | Sección DDL Existe |
|-----|-------------------|---------------------|-------------------|
| OQI-001 | auth | 12 | ✅ Sí |
| OQI-002 | trading, portfolio | 18, 8 | ✅ Sí |
| OQI-003 | market_data | 7 | ⚠️ Incompleta |
| OQI-004 | [ninguno] | N/A | ❌ No |
| [completar para 11 OQIs] | | | |

## Coherencia por Schema

| Schema | Tablas DDL Real | Tablas OQI Doc | OQI Asignado | Estado |
|--------|-----------------|----------------|--------------|--------|
| auth | 12 | 12 | OQI-001 | ✅ MATCH |
| trading | 18 | 18 | OQI-002 | ✅ MATCH |
| portfolio | 8 | 8 | OQI-002 | ✅ MATCH |
| market_data | 7 | 5 | OQI-003 | ❌ GAP (-2) |
| audit | 11 | 0 | - | ❌ NO DOCUMENTADO |
| [etc.] | | | | |

## Discrepancias Identificadas

### Discrepancia 1: Schema `market_data`
- **Real:** 7 tablas
- **Documentado:** 5 tablas
- **Gap:** 2 tablas no documentadas
- **Tablas faltantes:** [listar nombres si posible]

### Discrepancia 2: Schema `audit` sin OQI
- **Real:** 11 tablas
- **Documentado:** No asignado a ningún OQI
- **Acción requerida:** Agregar sección DDL en OQI-009

[Listar todas las discrepancias]

## Schemas Huérfanos (sin OQI)
1. [Schema X]: Y tablas - No asignado a ningún OQI

## OQIs sin Sección DDL
1. OQI-004 (Portfolio Management): Falta sección "Schemas DDL Asignados"
2. OQI-006 (Education): Falta sección
[etc.]

## Métricas de Coherencia

| Métrica | Valor | Estado |
|---------|-------|--------|
| Schemas documentados | 8/11 (73%) | ⚠️ MEDIO |
| Conteos exactos (match) | 6/8 (75%) | ⚠️ MEDIO |
| OQIs con sección DDL | 6/11 (55%) | ❌ BAJO |
| Schemas huérfanos | 3/11 (27%) | ❌ ALTO |

**Score Global de Coherencia:** 65% (MEDIO)

## Recomendaciones

### P0-CRITICO
1. Documentar schemas huérfanos en sus OQIs correspondientes
2. Corregir conteos de tablas en OQI-003, OQI-005

### P1-ALTO
1. Agregar sección "Schemas DDL Asignados" en 5 OQIs faltantes
2. Actualizar descripciones de tablas obsoletas

### P2-MEDIO
1. Agregar información de funciones/triggers/enums en secciones DDL
2. Crear diagramas ER por schema

## Próximos Pasos
1. Ejecutar correcciones P0 (SA-XX)
2. Ejecutar correcciones P1 (SA-YY)
3. Re-validar coherencia después de fixes
```

## Restricciones

- **MODO READ-ONLY:** NO modificar ningún archivo
- Usar Glob para listar archivos, Grep para contar CREATE TABLE
- Usar Read para leer contenido de archivos específicos
- NO ejecutar queries SQL, solo análisis estático de archivos .sql
- Generar reporte markdown estructurado

## Output Esperado

Un reporte markdown completo con:
- Inventarios completos (DDL real vs. OQI documentado)
- Tabla de coherencia schema por schema
- Discrepancias identificadas y clasificadas
- Métricas de coherencia (porcentajes)
- Recomendaciones priorizadas (P0/P1/P2)
- Score global de coherencia

**Archivo de salida:** Documento temporal o reporte directo al orquestador.

**Compromiso:** Generar análisis completo de coherencia DDL ↔ OQI con datos verificados.