---
name: proceso-discovery-machote
description: >
  Patrón de discovery para modelar entidades regulatorias (papeles de trabajo,
  cédulas, oficios, informes, expedientes, actas, dictámenes). Antes de modelar
  desde el Artículo legal, pedir al usuario el machote oficial real (template
  institucional). El Art. define el mínimo normativo; el machote revela el
  contrato institucional real con prácticas no codificadas pero exigidas.
  Cargar al iniciar la modelación de cualquier entidad nueva que represente
  un documento normativo emitido por una institución regulatoria (OIC, INE,
  SAT, etc.), durante /swl:discutir-fase de un módulo regulatorio, o cuando
  el usuario rechaza un primer diseño por "faltan campos del documento real".
version: "1.0.0"
herramientasPermitidas: [Read, Grep, Glob]
exclusiones:
  - "No cargar para entidades NO regulatorias (productos, usuarios, sesiones, eventos de log) — el machote no aplica a entidades de aplicación generales."
  - "No cargar cuando el modelo de la entidad ya está estabilizado y solo se va a agregar 1-2 campos — el discovery completo es overhead innecesario para ajustes pequeños."
  - "No cargar para refactor de entidad existente que ya tiene 6+ meses en producción — el machote ya se consolidó implícitamente en el modelo; cualquier diferencia es decisión de evolución, no de discovery."
  - "No cargar para CRUD administrativo simple (catálogos, configuraciones) — esos no tienen contrato institucional rico; cargar `discutir-fase` regular."
evolvable: true
---

# Proceso Discovery Machote

Patrón obligatorio antes de modelar entidades regulatorias.

## Cuándo NO cargar

- La entidad NO es regulatoria (un producto de catálogo, una sesión de usuario, un evento de log).
- El modelo ya está estabilizado en producción y solo se agregan 1-2 campos.
- Es refactor de entidad consolidada (≥6 meses prod) — cargar reglas de refactor, no de discovery.
- Es CRUD administrativo simple sin contrato institucional rico.

## El gap conceptual

**El Artículo legal define el mínimo normativo. El machote oficial revela el contrato institucional real.**

Caso real SIGAF ADR-081 IPHI (2026-05-15). El Informe de Presunta Hipótesis de Irregularidad (IPHI) se modeló inicialmente desde Art. 44 DBC_FISC_OIC, que enumera 10 fracciones (I-X) de contenido obligatorio:

> Art. 44. El informe contendrá:
> I.   Antecedentes
> II.  Marco normativo
> III. Hechos
> IV.  Análisis
> V.   Presunto daño patrimonial
> VI.  Cuantificación del daño
> VII. Sujetos involucrados
> VIII. Pruebas documentales
> IX.  Conclusiones
> X.   Auditores que intervinieron

Modelo Pydantic + tabla SQL creados con esas 10 secciones. Commit inicial Fase 1.

Tras Fase 1, el usuario proporcionó el machote oficial real `OIC-DATIC-02-ESP-2025-IPHI-01.docx`. Reveló **7 extensiones institucionales NO presentes en Art. 44**:

| # | Extensión del machote | NO está en Art. 44 |
|---|---|---|
| 1 | Distinción `presunto_dano_patrimonial` (directo) vs `perjuicio_total_estimado` (agregado: daño + depreciación + costo oportunidad) | Art. 44 fracción V/VI no distinguen |
| 2 | Observaciones origen N:M con `hallazgo_identificador` (tabla puente `iphi_observacion_origen`) | Art. 44 no define la relación |
| 3 | `procedimientos_contratacion_relacionados` JSONB (lista de LP-INE asociadas) | No aparece en el Art. |
| 4 | `normas_infringidas` JSONB estructurado `[{norma, articulo, contenido}]` | Art. 44 dice "marco normativo" sin estructura |
| 5 | `desglose_dano_patrimonial` JSONB (auditabilidad del cálculo) | No exigido por Art. |
| 6 | Estructura específica de `antecedentes` JSONB con 6 sub-secciones | Art. 44 dice "antecedentes" sin desglose |
| 7 | Roles claros de `auditores_integrantes`: Elaboró/Revisó/Supervisó/Autorizó mapeando a flujo VBO de 3 niveles | Art. 44 dice "auditores que intervinieron" sin roles |

Refactor de Fase 1 = ~600 LOC de cambios + 1 tabla puente nueva + modelo Pydantic re-estructurado. Si el machote hubiera estado disponible al inicio, ese refactor no existiría.

## El patrón

### Paso 1: identificar si la entidad es regulatoria

Una entidad es regulatoria cuando representa un **documento normativo emitido por una institución**:

- Papel de trabajo (de auditoría).
- Cédula (preliminar, definitiva, observación derivada).
- Oficio (de investigación, de notificación, de respuesta).
- Informe (de hipótesis, de irregularidad, de auditoría).
- Acta (de inicio, de hechos, de cierre).
- Dictamen.
- Expediente (con composición fija de documentos).
- Resolución.

NO es regulatoria:
- Producto de catálogo, usuario, sesión, configuración.
- Evento de log o auditoría técnica.
- Entidad transaccional puramente operacional (pago, factura interna).

### Paso 2: durante /swl:discutir-fase, preguntar explícitamente

Antes de modelar la entidad, plantear al usuario las 3 preguntas:

1. **¿Existe un machote oficial real del documento?** (formato Word/PDF emitido por la institución, no template generado por el equipo).
2. **¿Existe un Artículo legal o Reglamento que defina el contenido obligatorio?** (cita exacta del Art.).
3. **Si solo hay Art., ¿hay práctica institucional documentada (manuales operativos, guías, ejemplos previos)?**

Estados posibles del discovery:

| Machote | Art. legal | Acción |
|---|---|---|
| ✅ Disponible | ✅ Disponible | Modelar desde machote + verificar que cubre todos los puntos del Art. (el Art. es el mínimo, el machote es el contrato real). |
| ✅ Disponible | ❌ No disponible | Modelar desde machote. Marcar campos como "exigidos por práctica institucional, sin base legal explícita". |
| ❌ No disponible | ✅ Disponible | Modelar desde Art. con marca explícita "modelo derivado solo del Art. — pendiente de validar contra machote oficial cuando el usuario lo proporcione". Crear DT formal `DT-MODELO-{ENTIDAD}-MACHOTE-PENDIENTE` con criterio de disparo: "modelo se considera estable cuando el machote oficial confirme o requiera ajustes". |
| ❌ No disponible | ❌ No disponible | Escalar al usuario: "No hay fuente oficial ni machote — ¿la entidad existe como tal? ¿O debería modelarse como entidad de aplicación sin contrato institucional?". |

### Paso 3: extraer del machote, no del modelo mental

Cuando el machote esté disponible, leerlo COMPLETO con `markitdown` (regla global `markitdown.md` para .docx/.pdf):

```bash
markitdown OIC-DATIC-02-ESP-2025-IPHI-01.docx > /tmp/machote-iphi.md
```

Auditar cada sección visible:

- **Tablas estructuradas**: cada fila/columna → posible columna de la entidad o tabla puente.
- **Campos repetidos con formato uniforme**: posible tipo enum o catálogo.
- **Secciones con sub-secciones**: posible JSONB estructurado.
- **Espacios para firma/aprobación**: posible flujo de estados (VBO, aprobación multi-nivel).
- **Numeración de párrafos**: posible array o relación 1:N.
- **Referencias a otros documentos**: posibles FKs a otras entidades.

NO inferir campos del modelo mental — extraer literal del machote.

### Paso 4: registrar la divergencia Art. ↔ machote

En el ADR de la entidad (o sección `### Modelo derivado` del schema):

```markdown
## Origen del modelo

**Artículo legal**: DBC_FISC_OIC Art. 44 (10 fracciones I-X).
**Machote oficial**: OIC-DATIC-02-ESP-2025-IPHI-01.docx (~25 páginas).

**Extensiones del machote sobre el Art.**:
1. `perjuicio_total_estimado` distinto de `presunto_dano_patrimonial`.
2. Observaciones origen N:M con `hallazgo_identificador`.
3. `procedimientos_contratacion_relacionados` JSONB.
4. ...

**Cobertura**: el modelo cubre 100% del Art. 44 + 7 extensiones del machote.
**Divergencia**: cuando el Art. y el machote contradicen, prevalece el machote (es el contrato real de la institución).
```

## Anti-patrones

- **Modelar desde solo el Art. legal sin pedir el machote** — el modelo cubre el mínimo legal pero pierde 30-50% del contenido institucional real. Refactor garantizado cuando aparezca el machote.
- **Modelar desde un machote sin verificar contra el Art.** — riesgo de campos derivados de versiones obsoletas del documento. El Art. es la fuente de verdad legal; el machote puede tener campos "heredados" de versiones previas.
- **Asumir que el machote está internalizado en el modelo del equipo** — el equipo del agente NO tiene el machote en su contexto entrenado. Pedirlo explícitamente al usuario; no inferir.
- **Diferir el machote a "después del MVP"** — el refactor para incorporar el machote en una entidad regulatoria es 80% reescritura del modelo + cascada a schemas Pydantic + frontend forms. NO es post-MVP barato.
- **Aceptar un machote en formato propietario sin convertirlo a markdown legible** — abrir el Word/PDF directamente lleva al modelo a olvidar campos. Convertir SIEMPRE con `markitdown` y auditar el markdown resultante.

## Gotchas / Errores comunes no obvios

- **El machote tiene campos "sólo para impresión" que NO son datos de la entidad**: encabezados con logos, secciones de "Para uso oficial", footers. Esos NO van al modelo. Discriminar mientras se audita el markdown extraído.
- **El machote tiene campos calculados o derivados que SE ALMACENAN para auditoría**: ej. `perjuicio_total_estimado` se calcula desde 3 sumandos pero se persiste explícitamente porque el documento legal lo cita como cifra. Almacenar como columna calculada con backfill o como dato denormalizado con trigger de recálculo.
- **El machote evoluciona entre años fiscales** (`OIC-DATIC-02-ESP-2024-...` vs `OIC-DATIC-02-ESP-2025-...`): el modelo debe versionar el contrato. Agregar `machote_version: str` a la entidad para registrar contra qué versión se emitió cada documento. Migrar es costoso si no se versiona desde el inicio.
- **El usuario puede proporcionar un machote "informal" que es solo un Word con texto libre**: discriminar entre machote oficial (emitido por la institución con código de documento, fecha de actualización, autoridad emisora) vs borrador interno del equipo. El borrador NO es contrato — usar Art. como base con DT formal.
