---
id: PROMPT-SA-09
agent_id: SA-09
model: claude-sonnet-4.5
type: General background
fase: FASE-2
scope: Documentar DDL drift en 6 OQI READMEs
mode: write
created: 2026-02-06
---

# PROMPT-SA-09: Documentar DDL Drift en OQI READMEs (P1)

## Contexto

Eres un agente ejecutor de documentación técnica. Se ha identificado un gap P1-ALTO: los **READMEs de los módulos OQI NO documentan qué schemas DDL están asignados** a cada módulo.

**Proyecto:** trading-platform
**Problema:** Cada OQI (Own-Query-Integrate) debería tener una sección "Schemas DDL Asignados" que liste qué schemas de PostgreSQL le corresponden, pero actualmente faltan o están incompletos.

**Total schemas DDL:** 11 (auth, trading, education, financial, investment, ml, llm, audit, portfolio, market_data, feature_flags)

**OQIs a actualizar (6 principales):**
1. `docs/modulos-negocio/definitions/OQI-001-AUTH/README.md`
2. `docs/modulos-negocio/definitions/OQI-002-TRADING/README.md`
3. `docs/modulos-negocio/definitions/OQI-003-MARKET-DATA/README.md`
4. `docs/modulos-negocio/definitions/OQI-005-FINANCIAL/README.md`
5. `docs/modulos-negocio/definitions/OQI-007-ML/README.md`
6. `docs/modulos-negocio/definitions/OQI-009-AUDIT/README.md`

## Instrucciones

### PASO 1: Mapear schemas DDL a OQIs

**Fuente de verdad:** `database/schemas/` (contiene archivos `.sql` por schema)

Mapeo esperado:
- **OQI-001 (Auth):** schema `auth`
- **OQI-002 (Trading):** schemas `trading`, `portfolio`
- **OQI-003 (Market Data):** schema `market_data`
- **OQI-005 (Financial):** schema `financial`
- **OQI-007 (ML):** schemas `ml`, `llm`
- **OQI-009 (Audit):** schema `audit`

Verificar contando tablas reales en cada schema:
1. Leer archivo DDL de cada schema (ej: `database/schemas/01-auth.sql`)
2. Contar `CREATE TABLE` statements
3. Listar nombres de tablas principales

### PASO 2: Agregar sección en cada README

Para cada uno de los 6 OQI READMEs:

1. **Leer el README actual**
2. **Verificar si ya existe sección "Schemas DDL Asignados"**
   - Si existe: actualizar
   - Si NO existe: agregar después de la sección "Alcance" o "Descripción"

3. **Formato de la nueva sección:**

```markdown
## Schemas DDL Asignados

Este módulo gestiona los siguientes schemas de base de datos:

### Schema: `auth`
- **Tablas:** 12
- **Tablas principales:**
  - `users` - Usuarios del sistema
  - `roles` - Roles de autorización
  - `permissions` - Permisos granulares
  - `user_roles` - Asignación usuarios-roles
  - `sessions` - Sesiones activas
  - [listar top 5-8 tablas más importantes]

- **Ubicación DDL:** `database/schemas/01-auth.sql`
- **Enums utilizados:** `user_status`, `session_status`, `verification_status`
- **Relaciones con otros schemas:**
  - `audit.user_actions` → FK a `auth.users`
  - Casi todos los schemas tienen FK a `auth.users`

[Repetir para cada schema asignado al OQI]
```

4. **Usar herramienta Edit para agregar la sección:**
   - Identificar `old_string` (ej: sección siguiente)
   - `new_string` = sección DDL + sección siguiente
   - NO usar placeholders

### PASO 3: Validar coherencia

Después de actualizar los 6 READMEs:
- Verificar que TODOS los 11 schemas DDL estén documentados en algún OQI
- Verificar que no haya duplicación (un schema en 2 OQIs)
- Verificar conteos de tablas correctos

## Restricciones

- **MODO WRITE:** Modificar solo los 6 READMEs especificados
- **EDICIÓN SEGURA:** Agregar sección nueva, NO modificar secciones existentes
- **PROHIBIDO:** Placeholders, eliminar contenido existente
- **OBLIGATORIO:** Contar tablas reales desde archivos DDL, NO asumir
- Mantener formato markdown consistente con el resto del README

## Output Esperado

```markdown
## Resumen de Actualizaciones

### OQI-001-AUTH/README.md
**Sección agregada:** "Schemas DDL Asignados"
**Schema documentado:** `auth` (12 tablas)
**Ubicación:** Después de sección "Alcance"

### OQI-002-TRADING/README.md
**Sección agregada:** "Schemas DDL Asignados"
**Schemas documentados:** `trading` (18 tablas), `portfolio` (8 tablas)
**Ubicación:** Después de sección "Descripción"

[etc. para los 6 OQIs]

## Cobertura de Schemas DDL

| Schema | OQI Asignado | Tablas | Estado |
|--------|--------------|--------|--------|
| auth | OQI-001 | 12 | ✅ Documentado |
| trading | OQI-002 | 18 | ✅ Documentado |
| portfolio | OQI-002 | 8 | ✅ Documentado |
| market_data | OQI-003 | 7 | ✅ Documentado |
| financial | OQI-005 | 15 | ✅ Documentado |
| ml | OQI-007 | 9 | ✅ Documentado |
| llm | OQI-007 | 6 | ✅ Documentado |
| audit | OQI-009 | 11 | ✅ Documentado |
| education | OQI-006 | 10 | ⚠️ NO en scope (solo 6 OQIs) |
| investment | OQI-008 | 4 | ⚠️ NO en scope |
| feature_flags | OQI-011 | 3 | ⚠️ NO en scope |

## Validación
✅ 6 READMEs actualizados
✅ 8 schemas documentados (de 11 total)
✅ Conteos verificados desde DDL real
✅ No hay duplicación de schemas
✅ Formato markdown válido
```

**Compromiso:** Actualizar 6 OQI READMEs con secciones DDL completas y verificadas.