workspace-v1/control-plane/orchestration/directivas/simco/SIMCO-ESCALAMIENTO.md

SIMCO: ESCALAMIENTO (Al Product Owner)

Version: 1.0.0 Fecha: 2025-12-12 Aplica a: TODO agente que encuentre ambiguedad o informacion faltante Prioridad: OBLIGATORIA - Aplica PRINCIPIO-NO-ASUMIR

---

RESUMEN EJECUTIVO

Si no esta definido en la documentacion, NO asumir. PREGUNTAR. Nunca implementar basado en suposiciones. Escalar al Product Owner cuando hay ambiguedad.

---

PRINCIPIO FUNDAMENTAL

╔══════════════════════════════════════════════════════════════════════╗
║                                                                       ║
║   REGLA DE ORO: "Si no esta documentado, NO asumir. PREGUNTAR."     ║
║                                                                       ║
║   PROHIBIDO:                                                          ║
║   - Asumir valores/comportamientos no documentados                   ║
║   - Inventar requisitos                                               ║
║   - Tomar decisiones de negocio sin autorizacion                     ║
║   - Implementar "lo que parece logico" sin confirmacion              ║
║                                                                       ║
║   OBLIGATORIO:                                                        ║
║   - Detener trabajo cuando falta informacion critica                 ║
║   - Documentar pregunta claramente                                   ║
║   - Escalar al Product Owner                                          ║
║   - Esperar respuesta antes de continuar                             ║
║   - Documentar decision del PO antes de implementar                  ║
║                                                                       ║
╚══════════════════════════════════════════════════════════════════════╝

---

CUANDO ESCALAR

1. Informacion Faltante en Documentacion

casos_de_escalamiento:
  - Tabla/entidad mencionada pero sin definicion de columnas
  - Endpoint mencionado pero sin especificacion de payload
  - Pagina mencionada pero sin definicion de componentes
  - Regla de negocio ambigua o incompleta
  - Valores de enum no especificados
  - Validaciones no documentadas
  - Comportamiento de error no definido
  - Limites/umbrales no especificados
  - Orden de prioridad no claro
  - Dependencias entre features no definidas

2. Ambiguedad en Requerimientos

casos_de_escalamiento:
  - Requisito que puede interpretarse de multiples formas
  - Contradiccion entre documentos
  - Alcance no claramente definido
  - Criterios de aceptacion vagos
  - Casos edge no cubiertos
  - Comportamiento en condiciones especiales no definido

3. Decisiones de Negocio

casos_de_escalamiento:
  - Cambio que afecta experiencia de usuario
  - Modificacion de flujos existentes
  - Nuevas restricciones o validaciones
  - Priorizacion entre alternativas
  - Trade-offs tecnico-negocio
  - Impacto en otros sistemas/integraciones

4. Contradicciones Entre Documentos

casos_de_escalamiento:
  - Spec dice una cosa, MVP otra
  - Requisito funcional contradice requisito tecnico
  - Diagrama no coincide con descripcion
  - Versiones de documentos en conflicto

---

COMO NO ESCALAR (ANTI-PATRONES)

INCORRECTO:
  - "No encontre la informacion, voy a asumir..."
  - "Parece logico que sea asi, voy a implementar..."
  - "Seguramente el PO quiso decir..."
  - "En otros proyectos lo hacemos asi..."
  - "Preguntare despues de implementar..."

CORRECTO:
  - "No encontre la especificacion de X, escalo al PO"
  - "La documentacion es ambigua en Y, escalo al PO"
  - "Detuve la implementacion hasta clarificar Z con PO"

---

FORMATO DE ESCALAMIENTO

Template de Consulta al PO

## CONSULTA AL PRODUCT OWNER

**Fecha:** {YYYY-MM-DD HH:MM}
**Agente:** {Nombre del agente}
**Tarea:** [{TAREA-ID}] {Titulo}
**Fase:** {Analisis | Planeacion | Ejecucion}

### Contexto

{Describir brevemente que estas haciendo y donde encontraste el problema}

### Informacion Encontrada

{Listar lo que SI encontraste en la documentacion}
- Documento X, linea Y: "{texto relevante}"
- Documento Z: {informacion relacionada}

### Informacion Faltante / Ambigua

{Describir claramente que falta o es ambiguo}
- No se especifica: {detalle}
- Es ambiguo porque: {explicacion}

### Pregunta Especifica

{Formular pregunta clara y concisa}

**Opciones identificadas (si aplica):**
1. Opcion A: {descripcion} - Implicaciones: {X}
2. Opcion B: {descripcion} - Implicaciones: {Y}
3. Opcion C: {descripcion} - Implicaciones: {Z}

### Impacto de No Resolver

{Que pasa si no se resuelve esta duda}
- Bloquea: {tarea/feature}
- Riesgo: {descripcion del riesgo}

### Estado

**[ ] PENDIENTE RESPUESTA**
[ ] RESPONDIDO
[ ] IMPLEMENTADO

---

EJEMPLOS DE ESCALAMIENTO

Ejemplo 1: Valores de Enum No Especificados

## CONSULTA AL PRODUCT OWNER

**Fecha:** 2025-12-12 14:30
**Agente:** Database-Agent
**Tarea:** [DB-042] Crear modulo de Proyectos
**Fase:** Analisis

### Contexto

Estoy trabajando en la tabla `projects` segun MVP-APP.md seccion 4.1.
La documentacion menciona que los proyectos tienen un "status" pero
no especifica los valores posibles.

### Informacion Encontrada

- MVP-APP.md linea 250: "Los proyectos tienen un status que cambia
  a lo largo del ciclo de vida"
- No hay especificacion de valores validos de status

### Informacion Faltante

- Valores del enum `project_status`
- Transiciones validas entre estados
- Estado inicial por defecto

### Pregunta Especifica

Cuales son los valores validos para el status de un proyecto?

**Opciones identificadas:**
1. ['draft', 'active', 'completed', 'archived']
2. ['pending', 'in_progress', 'done', 'cancelled']
3. Otro conjunto de valores

### Impacto de No Resolver

- Bloquea: Creacion de tabla projects
- Riesgo: Implementar valores incorrectos que requieran migracion

### Estado

**[X] PENDIENTE RESPUESTA**

Ejemplo 2: Comportamiento de Error No Definido

## CONSULTA AL PRODUCT OWNER

**Fecha:** 2025-12-12 15:00
**Agente:** Backend-Agent
**Tarea:** [BE-015] Implementar validacion de codigo unico
**Fase:** Ejecucion

### Contexto

Implementando validacion de codigo unico en ProjectService.
La documentacion indica que el codigo debe ser unico, pero no
especifica que hacer cuando ya existe.

### Informacion Encontrada

- RF-PROJ-003: "El codigo del proyecto debe ser unico en el sistema"

### Informacion Faltante

- Mensaje de error a mostrar al usuario
- Si debe sugerir un codigo alternativo
- Si debe permitir reutilizar codigos de proyectos archivados

### Pregunta Especifica

Cual es el comportamiento esperado cuando un usuario intenta
crear un proyecto con un codigo que ya existe?

**Opciones:**
1. Rechazar con mensaje generico "Codigo ya existe"
2. Sugerir codigo alternativo (ej: PROJ-001-1)
3. Permitir si el proyecto original esta archivado

### Impacto de No Resolver

- Riesgo: UX pobre si mensaje no es util
- Riesgo: Confusion si comportamiento no es intuitivo

### Estado

**[X] PENDIENTE RESPUESTA**

---

FLUJO DE ESCALAMIENTO

1. Detectar informacion faltante/ambigua
      |
      v
2. Buscar exhaustivamente en documentacion
   |  - docs/01-requerimientos/
   |  - docs/02-especificaciones-tecnicas/
   |  - ADRs
   |  - Inventarios
      |
      v
3. Si NO se encuentra:
      |
      v
4. Documentar consulta (usar template)
      |
      v
5. DETENER trabajo en esta parte
   |  - No asumir
   |  - No implementar parcialmente
   |  - Marcar tarea como BLOQUEADA
      |
      v
6. Continuar con otras tareas si es posible
      |
      v
7. Esperar respuesta del PO
      |
      v
8. Documentar respuesta recibida
      |
      v
9. Actualizar documentacion con la decision
      |
      v
10. Continuar implementacion

---

DOCUMENTAR RESPUESTA DEL PO

Cuando se Recibe Respuesta

## RESPUESTA DEL PRODUCT OWNER

**Fecha respuesta:** {YYYY-MM-DD}
**Respondido por:** {nombre/rol}

### Decision

{Transcribir o resumir la decision tomada}

### Justificacion (si se proporciono)

{Razon de la decision}

### Impacto en Implementacion

{Como afecta esto a la implementacion actual}

### Documentacion a Actualizar

- [ ] {documento 1}: {cambio}
- [ ] {documento 2}: {cambio}

### Estado

[ ] PENDIENTE RESPUESTA
**[X] RESPONDIDO**
[ ] IMPLEMENTADO

Actualizar Documentacion

DESPUES_de_recibir_respuesta:
  - Actualizar spec/requisito correspondiente
  - Agregar nota de clarificacion si aplica
  - Registrar decision en ADR si es significativa
  - Actualizar inventarios si hay cambio de alcance

---

DONDE REGISTRAR ESCALAMIENTOS

ubicacion:
  activos: "orchestration/escalamientos/ACTIVOS.md"
  resueltos: "orchestration/escalamientos/HISTORICO.md"

formato_registro:
  - Fecha
  - Agente
  - Tarea relacionada
  - Resumen de pregunta
  - Estado (PENDIENTE/RESUELTO)
  - Link a detalle

---

SEVERIDAD DE BLOQUEO

CRITICO:
  descripcion: "Bloquea toda la tarea"
  accion: "Detener completamente, escalar inmediatamente"
  ejemplo: "No se sabe que tablas crear"

ALTO:
  descripcion: "Bloquea parte significativa"
  accion: "Detener esa parte, continuar resto si es posible"
  ejemplo: "Falta definicion de un campo importante"

MEDIO:
  descripcion: "Puede implementarse parcialmente"
  accion: "Implementar lo claro, marcar TODO para lo ambiguo"
  ejemplo: "Mensaje de error no definido"

BAJO:
  descripcion: "Detalle menor"
  accion: "Implementar con valor razonable, documentar asuncion"
  ejemplo: "Longitud maxima de campo de texto"

---

CUANDO NO ESCALAR

NO_escalar_si:
  - La informacion ESTA en la documentacion (buscar mejor)
  - Es una decision puramente tecnica (consultar Architecture-Analyst)
  - Es un bug (reportar como bug, no como ambiguedad)
  - Es una mejora sugerida (documentar como sugerencia)

CONSULTAR_otros_agentes_si:
  - Duda tecnica: Architecture-Analyst
  - Duda de implementacion existente: Agente de capa
  - Duda de proceso: Orquestador/Tech-Leader

---

METRICAS DE ESCALAMIENTO

metricas_a_monitorear:
  - Numero de escalamientos por tarea
  - Tiempo promedio de respuesta del PO
  - Escalamientos que podian evitarse (documentacion existia)
  - Escalamientos que resultaron en cambio de spec

objetivo:
  - Reducir escalamientos innecesarios
  - Mejorar calidad de documentacion
  - Minimizar bloqueos por falta de informacion

---

REFERENCIAS

• Principio relacionado: @PRINCIPIOS/PRINCIPIO-NO-ASUMIR.md
• Doc Primero: @PRINCIPIOS/PRINCIPIO-DOC-PRIMERO.md
• Ciclo de tarea: @SIMCO/SIMCO-TAREA.md

---

Version: 1.0.0 | Sistema: SIMCO | Mantenido por: Tech Lead