# Guia Para IA: Generar Paquete Modular Desde Un Prompt Legacy

Esta guia esta pensada para otra IA que necesite transformar un prompt legacy grande en la arquitectura modular actual de Medusa.

Objetivo:
- recibir un prompt viejo o una descripcion funcional
- separar correctamente reglas globales, reglas por area y secuencias deterministicas
- devolver prompts modulares y flujos V1 consistentes con el sistema real

Complementa:
- [GUIA_PARA_IA_GENERAR_FLUJOS_V1.md](/c:/Apache24/htdocs/sidelink/backend/IA/GUIA_PARA_IA_GENERAR_FLUJOS_V1.md)
- [GUIA_TECNICA_FLOW_STANDARD_V1.md](/c:/Apache24/htdocs/sidelink/backend/IA/GUIA_TECNICA_FLOW_STANDARD_V1.md)
- [FLOW_STANDARD_V1.md](/c:/Apache24/htdocs/sidelink/backend/IA/FLOW_STANDARD_V1.md)
- [GUIA_TECNICA_CATALOGO_RUNTIME.md](/c:/Apache24/htdocs/sidelink/backend/IA/GUIA_TECNICA_CATALOGO_RUNTIME.md)

## Objetivo del sistema actual

La arquitectura actual funciona asi:

1. `prompt_base`
- define identidad, tono, reglas globales y formatos compartidos

2. `prompt_core`
- clasifica intenciones
- extrae slots
- sugiere continuacion de flujo
- no habla con el cliente

3. `prompt_area`
- define reglas del dominio
- ejemplo: soporte, ventas, cobranza
- no define la secuencia exacta del caso

4. `flujo_*`
- define secuencia, ramas, acciones y cierres deterministas

5. runtime backend
- decide el siguiente paso del flujo
- ejecuta actions reales

6. GPT final
- redacta el mensaje natural al cliente

Regla central:
- la IA no ejecuta el flujo
- el runtime si

## Cuando usar esta guia

Usar esta guia si recibis:
- un prompt legacy largo que mezcla tono, reglas, preguntas y derivaciones
- un documento de negocio en texto libre
- una lista de requisitos por area
- una transcripcion de como deberia trabajar el bot

Y tenes que devolver:
- prompts modulares
- flujos V1

## Qué debe producir la IA

La IA debe ser capaz de devolver un paquete modular con alguno de estos formatos:

### Formato recomendado en JSON

```json
{
  "prompts": [
    {
      "clave": "prompt_base",
      "content": "..."
    },
    {
      "clave": "prompt_soporte",
      "content": "..."
    }
  ],
  "flows": [
    {
      "clave": "flujo_soporte",
      "content": {
        "id": "flujo_soporte_v1",
        "version": 1,
        "nombre": "Soporte tecnico",
        "intent_principal": "prompt_soporte",
        "settings": {
          "entry_step": "pedir_dni"
        },
        "tool_permissions": {},
        "slots": {},
        "backend_facts": {},
        "steps": []
      }
    }
  ],
  "observaciones": []
}
```

### Formato alternativo en bloques

Si el usuario no pide JSON estricto, tambien puede responder con:
- `prompt_base`
- `prompt_soporte`
- `flujo_soporte`

cada uno en su bloque listo para copiar y pegar.

## Regla de oro: dónde va cada cosa

### Va en `prompt_base`

Solo reglas globales y estables, por ejemplo:
- identidad del bot
- tono general
- idioma
- reglas comunes de seguridad
- formato general de derivacion
- reglas comunes sobre no inventar
- reglas comunes sobre links, emojis o estilo

### Va en `prompt_core`

Solo si cambia la arquitectura de clasificacion o aparecen nuevas intenciones.

Ejemplos:
- lista de intenciones nuevas
- convenciones de salida del core
- reglas estructurales sobre slots o bloques sugeridos

Regla practica:
- no regenerar `prompt_core` por cada tenant salvo que realmente cambie el catalogo de intenciones o la logica base

### Va en `prompt_area`

Reglas de negocio o lenguaje propias de un dominio.

Ejemplos:
- soporte: evitar preguntas redundantes si hay indicios claros de falla fisica
- ventas: priorizar captura de datos minimos
- cobranza: no confirmar acreditaciones manuales no validadas

Importante:
- el prompt de area no debe definir una secuencia detallada paso a paso
- si hay orden, ramas o requisitos para derivar, eso va al flujo

### Va en `flujo_*`

Todo lo deterministico y secuencial.

Ejemplos:
- pedir DNI
- validar cliente
- si falla buscar_cliente -> pedir otro DNI
- si estado administrativo = cortado -> derivar cobranza
- si tipo de problema = sin_servicio -> seguir cierta rama
- pedir plan
- pedir DNI
- transferir a operador

## Cómo desarmar un prompt legacy

Si recibis un prompt grande, seguí este proceso:

### Paso 1. Detectar reglas globales

Buscar:
- identidad
- tono
- idioma
- formato de listas
- reglas de links
- reglas de emojis
- formatos de resumen para transferencia

Eso va a `prompt_base`.

### Paso 2. Detectar áreas o dominios

Buscar fragmentos que hablen de:
- soporte
- ventas
- cobranza
- baja
- mudanza
- cambio de titular

Cada dominio deberia transformarse en un `prompt_area` si tiene reglas propias.

### Paso 3. Detectar secuencias operativas

Buscar frases como:
- primero pedir X
- luego validar Y
- si pasa A, derivar
- si pasa B, preguntar C
- si no se encuentra cliente, pedir otro DNI

Eso no debe quedar en prompts largos.
Eso debe convertirse en un `flujo_*` V1.

### Paso 4. Detectar actions reales

Buscar mentions como:
- buscar cliente
- transferir a operador
- registrar compromiso

Eso debe modelarse como `action` en el flujo, no como texto libre.

### Paso 5. Detectar datos conversacionales vs hechos backend

Si el dato lo dice el cliente:
- va a `slots`

Si el dato lo confirma el sistema:
- va a `backend_facts`

Ejemplo:
- `dni_cuit`: slot
- `estado_administrativo`: backend_fact

## Reglas de separación obligatoria

### No poner en el flujo

No poner en `flujo_*`:
- tono
- emojis
- copy final de WhatsApp
- identidad del bot
- reglas generales de estilo

### No poner en prompts

No poner en `prompt_area` o `prompt_base`:
- secuencias lineales detalladas
- validaciones duras
- ramas por estado
- decisiones de `on_success`
- decisiones de `on_failure`

Eso debe ir al flujo.

### No poner en `prompt_core`

No usar `prompt_core` para:
- describir la personalidad del bot
- repetir instrucciones de negocio por area
- modelar secuencias de soporte o ventas

## Qué espera hoy el sistema

### Prompts

Claves esperadas:
- `prompt_base`
- `prompt_core`
- `prompt_soporte`
- `prompt_ventas`
- `prompt_cobranza`
- otras claves `prompt_*` reales del tenant

### Flujos

Claves esperadas:
- `flujo_soporte`
- `flujo_ventas`
- `flujo_cobranza`
- etc.

Convencion importante:
- el sistema deriva `prompt_soporte` -> `flujo_soporte`
- el `id` interno puede ser `flujo_soporte_v1`

## Qué hacer con reglas mezcladas en un prompt legacy

### Ejemplo 1

Texto legacy:
- "Sos Medu, hablás en español, tono profesional, si es soporte pedí DNI, validá cliente, si está cortado por deuda derivá a cobranza"

Descomposicion correcta:
- "Sos Medu..." -> `prompt_base`
- "tono profesional" -> `prompt_base`
- "si es soporte..." -> `prompt_soporte`
- "pedí DNI, validá cliente..." -> `flujo_soporte`
- "si está cortado por deuda..." -> `flujo_soporte` con `backend_facts.estado_administrativo` y `branch`

### Ejemplo 2

Texto legacy:
- "En ventas primero pedir localidad, zona, nombre, direccion, email, plan, dni y derivar"

Descomposicion correcta:
- la secuencia completa -> `flujo_ventas`
- el estilo comercial o reglas de captura -> `prompt_ventas`

## Qué hacer con un prompt legacy que mezcla copy de transferencia

Si el prompt viejo define formatos como:
- `Motivo:`
- `Resumen:`

Eso normalmente va en:
- `prompt_base` si aplica a varias areas
- `prompt_area` si solo aplica a una

No va al flujo.

El flujo solo deberia decidir:
- en qué paso derivar
- con qué action
- con qué `params.area`
- con qué `params.motivo` estructural

## Reglas sobre `prompt_core`

Por defecto, si no te piden rediseñar el core:
- no lo reescribas entero
- no inventes nuevas estructuras de salida
- no cambies nombres de intenciones ya existentes

Solo proponer cambios a `prompt_core` si:
- aparece una intencion nueva real
- cambia la convención de salida
- cambia el estándar de flujo

## Estructura recomendada del paquete de salida

Si el usuario te da contexto legacy y te pide modularizar, la respuesta ideal es:

1. `prompt_base`
2. `prompt_area` por cada dominio detectado
3. `flujo_*` por cada dominio con secuencia real
4. `observaciones`

### Ejemplo de `observaciones`

Usar `observaciones` para marcar:
- facts backend que el flujo espera pero hoy no están completamente normalizados
- dependencias de catálogos externos
- dudas no resueltas del negocio

Ejemplo:

```json
[
  "El flujo usa estado_administrativo como backend_fact esperado.",
  "Ventas requiere catalogo de planes por localidad para mostrar opciones reales."
]
```

## Heuristica práctica para decidir si algo va a flujo

Preguntate:

### Si la regla responde a:
- que decir
- como sonar
- que tono usar

Entonces va a prompt.

### Si la regla responde a:
- que dato pedir
- que tool ejecutar
- a que paso ir despues
- en que condicion derivar

Entonces va a flujo.

## Reglas para prompts de área

Los prompts de area deben ser:
- cortos
- específicos
- no redundantes con `prompt_base`
- no secuenciales

Ejemplo correcto de `prompt_soporte`:

```txt
AREA SOPORTE

Este prompt aplica a problemas tecnicos de internet, modem, cortes, lentitud o fallas de servicio.

Reglas:
- Prioriza la informacion tecnica ya confirmada por backend.
- Si el flujo ya definio el siguiente paso, no improvises una secuencia distinta.
- Si el cliente ya dio un dato que el flujo necesita, no lo vuelvas a pedir.
- No confirmes derivaciones ni acciones no ejecutadas por backend.
```

Ejemplo incorrecto de `prompt_soporte`:

```txt
Primero pedí el DNI, despues validá cliente, despues preguntá si hay luz roja...
```

Eso debe ir al flujo.

## Qué hacer con listados variables como planes o turnos

Si el prompt legacy trae:
- planes por localidad
- cobertura por zona
- turnos por sede
- servicios segun criterio

No meter eso:
- ni en `prompt_base`
- ni en `prompt_area`
- ni como lista fija dentro del flujo

Tratarlo como:
- catalogo runtime

Regla practica:
- el flujo captura criterios
- el runtime resuelve el catalogo
- GPT presenta los items resultantes

## Reglas para `prompt_base`

`prompt_base` debe contener solo invariantes globales:
- identidad
- tono general
- idioma
- formato de listas
- formato de links
- formato de derivacion
- reglas sobre no inventar

Debe evitar:
- secuencias por area
- reglas específicas de ventas o soporte si no aplican a todas las areas

## Qué hacer si falta contexto

Si el prompt legacy no permite desarmar bien el sistema, la IA debe:
- no inventar reglas de negocio
- producir un paquete minimo coherente
- dejar `observaciones` explicando lo que falta

Ejemplos:
- falta saber si ventas debe usar `buscar_cliente`
- falta saber si soporte debe derivar por deuda o solo informar
- falta saber si existe catalogo de planes por localidad

## Prompt recomendado para pedir modularizacion a otra IA

Podes usar literalmente esto:

```txt
Quiero que transformes este prompt legacy en la arquitectura modular actual de Medusa.

Necesito que me devuelvas:
1. prompt_base
2. prompts de area que hagan falta
3. flujos V1 asociados a esas areas
4. observaciones tecnicas si algo depende de backend o de catalogos

Reglas obligatorias:
- No mezcles formato legacy con Flow Standard V1.
- No pongas secuencias detalladas en prompts de area.
- Todo lo deterministico debe ir al flujo.
- prompt_base debe contener solo reglas globales.
- prompt_core no debe reescribirse salvo que sea estrictamente necesario.
- Los flujos deben respetar el standard V1 actual de Medusa.
- Si devolves JSON de flujo, debe ser valido.
- Si algo no se puede inferir con seguridad, marcarlo en observaciones en vez de inventarlo.

Este es el prompt legacy o contexto base:
[PEGAR ACA EL CONTEXTO]
```

## Checklist final para la IA

Antes de responder:

- separaste reglas globales de reglas por area
- separaste lenguaje/copy de secuencias
- todo lo deterministico quedo en `flujo_*`
- los prompts de area no contienen pasos lineales
- las tools aparecen como `action`
- los datos conversacionales quedaron en `slots`
- los hechos backend quedaron en `backend_facts`
- no inventaste nuevas keys fuera del standard