trading-platform/orchestration/tareas/TASK-2026-02-06-ANALISIS-INTEGRAL-DOCUMENTACION/subagentes/prompts/PROMPT-SA-15.md

id	agent_id	model	type	fase	scope	mode	created
PROMPT-SA-15	SA-15	claude-sonnet-4.5	General background	FASE-5	DDL-to-OQI coherence validation	read-only	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:

# 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.