workspace-v1/orchestration/directivas/simco/SIMCO-CONTROL-TOKENS.md

SIMCO: CONTROL DE TOKENS

Versión: 1.0.0 Sistema: SIMCO - NEXUS v4.0 Propósito: Gestionar límites de tokens para evitar errores de overflow Fecha: 2026-01-04

---

LÍMITES ESTABLECIDOS

LIMITES_TOKENS:
  absoluto: 25000      # Máximo por solicitud (error si se supera)
  alerta: 20000        # Warning - considerar desglose
  seguro: 18000        # Recomendado para operación normal
  minimo_efectivo: 5000 # Mínimo para tareas simples

---

PRESUPUESTO POR NIVEL DE CONTEXTO

PRESUPUESTO_CONTEXTO:
  L0_sistema:
    tokens: 4500
    incluye:
      - 6 Principios fundamentales (~600 tokens c/u = 3600)
      - Perfil de agente (~500 tokens)
      - ALIASES.yml resueltos (~400 tokens)
    obligatorio: true

  L1_proyecto:
    tokens: 3000
    incluye:
      - CONTEXTO-PROYECTO.md (~1500 tokens)
      - PROXIMA-ACCION.md (~500 tokens)
      - Inventario relevante (~1000 tokens)
    obligatorio: true

  L2_operacion:
    tokens: 2500
    incluye:
      - SIMCO de operación (~800 tokens)
      - SIMCO de dominio (~800 tokens)
      - Referencias específicas (~900 tokens)
    obligatorio: true

  L3_tarea:
    tokens: variable (max 8000)
    incluye:
      - Especificación de tarea
      - Código de referencia (solo líneas relevantes)
      - DDL relacionado (si aplica)
    dinamico: true

  TOTAL_BASE: 10000   # L0 + L1 + L2
  DISPONIBLE_TAREA: 8000  # 18000 - 10000
  MARGEN_SEGURIDAD: 7000  # Para respuesta del agente

---

ESTRATEGIAS DE MITIGACIÓN

1. Desglose de Tareas

CRITERIO_DESGLOSE:
  si_tarea_requiere: ">3000 tokens de contexto específico"
  accion: "DESGLOSAR en subtareas"

  reglas:
    - max_archivos_por_subtarea: 2
    - max_lineas_codigo_inline: 50
    - preferir_referencias: "file:line-range"

EJEMPLO_DESGLOSE:
  # MAL - Tarea muy grande
  tarea: "Crear módulo completo de notificaciones"
  tokens_estimados: 15000

  # BIEN - Desglosado
  subtareas:
    - ST-001: "Crear tabla notifications" # ~3000 tokens
    - ST-002: "Crear NotificationEntity"  # ~2500 tokens
    - ST-003: "Crear NotificationService"  # ~2500 tokens
    - ST-004: "Crear NotificationController" # ~2500 tokens

2. Carga de Contexto Escalonada

CARGA_ESCALONADA:
  paso_1_obligatorio:
    - L0_sistema (siempre)
    - L1_proyecto (siempre)

  paso_2_segun_operacion:
    - L2_operacion (solo SIMCO relevante)

  paso_3_bajo_demanda:
    - L3_tarea (solo lo directamente relacionado)
    - NO cargar código completo de archivos
    - Usar referencias: "Ver {archivo}:{lineas}"

3. Compactación de Contexto

TECNICAS_COMPACTACION:
  aliases:
    usar: "@ALIAS en lugar de rutas completas"
    ejemplo: "@DDL/schemas/auth/" vs "apps/database/ddl/schemas/auth/"
    ahorro: "~30% de caracteres"

  referencias_linea:
    usar: "file:line-range"
    ejemplo: "user.entity.ts:45-60"
    ahorro: "Evita incluir archivo completo"

  resumenes:
    usar: "Descripción de 1-2 líneas en lugar de contenido"
    ejemplo: "Ver DDL de tabla users (20 columnas, 3 índices)"
    ahorro: "~90% vs incluir DDL completo"

  herencia_contexto:
    usar: "Variables pre-resueltas del CONTEXT-MAP"
    evitar: "Repetir definiciones en cada delegación"

---

DETECCIÓN Y ALERTAS

Señales de Riesgo

ALERTA_AMARILLA:
  condicion: "tokens_estimados > 15000"
  accion: "Considerar desglose"
  mensaje: "Tarea grande - evaluar si se puede dividir"

ALERTA_NARANJA:
  condicion: "tokens_estimados > 20000"
  accion: "Desglose RECOMENDADO"
  mensaje: "Riesgo de truncamiento - dividir tarea"

ALERTA_ROJA:
  condicion: "tokens_estimados > 23000"
  accion: "Desglose OBLIGATORIO"
  mensaje: "Error inminente - NO proceder sin dividir"

Estimación de Tokens

ESTIMACION_RAPIDA:
  # Aproximaciones para cálculo mental
  1_token: "~4 caracteres en inglés"
  1_linea_codigo: "~15-25 tokens"
  1_archivo_pequeño: "~200-500 tokens"
  1_archivo_mediano: "~500-1500 tokens"
  1_archivo_grande: "~1500-3000 tokens"

  SIMCO_tipico: "~800-1200 tokens"
  PERFIL_tipico: "~400-600 tokens"
  TEMPLATE_tipico: "~600-1000 tokens"

---

PROTOCOLO SI SE EXCEDE LÍMITE

SI_ERROR_TOKENS:
  paso_1_identificar:
    - Revisar qué archivos están cargados
    - Identificar contenido más pesado

  paso_2_reducir:
    - Eliminar código inline no esencial
    - Usar referencias en lugar de contenido
    - Resumir en lugar de copiar

  paso_3_desglosar:
    - Dividir tarea en subtareas más pequeñas
    - Cada subtarea: 1-2 archivos máximo
    - Ejecutar secuencialmente

  paso_4_documentar:
    - Registrar en SESSION-TRACKING si fue por delegación
    - Agregar nota en PROXIMA-ACCION.md si fue tarea principal

---

INTEGRACIÓN CON CONTEXT-MAP

El CONTEXT-MAP.yml de cada proyecto debe respetar estos límites:

# En CONTEXT-MAP.yml
contexto_por_nivel:
  L0_sistema:
    tokens_estimados: 4500  # Verificar no excede
  L1_proyecto:
    tokens_estimados: 3000  # Verificar no excede
  L2_operacion:
    tokens_estimados: 2500  # Verificar no excede
  L3_tarea:
    tokens_max: 8000        # Límite dinámico

validacion_tokens:
  total_estimado: 18000     # Debe ser <= limite_seguro
  margen_disponible: 7000   # Para respuesta

---

CHECKLIST PRE-DELEGACION

Antes de delegar a subagente, ejecutar OBLIGATORIAMENTE:

CHECKLIST_OBLIGATORIO:
  archivo: "orchestration/checklists/CHECKLIST-PRE-DELEGACION.md"

CHECKLIST_RAPIDO:
  - [ ] 1. Tarea delimitada (max 2 archivos)
  - [ ] 2. Template correcto seleccionado
  - [ ] 3. Contexto heredado incluido
  - [ ] 4. Tokens estimados < 2,500
  - [ ] 5. Perfil COMPACT especificado

---

INTEGRACION CON DELEGACION

Referencia Obligatoria

Antes de delegar, ejecutar:

• orchestration/checklists/CHECKLIST-PRE-DELEGACION.md

Templates por Tokens

Tokens Disponibles	Template	Formato Herencia
>15,000	ESTANDAR o COMPLETA	Completo
8,000-15,000	ESTANDAR o MINIMA	Compactado
<8,000	MINIMA	Ultra-compactado

Perfiles Compactos

Para subagentes, usar:

• orchestration/agents/perfiles/compact/PERFIL-*-COMPACT.md
• Ahorro: ~550 tokens por perfil

---

REFERENCIAS

Documento	Proposito
PRINCIPIO-ECONOMIA-TOKENS.md	Principio fundamental
SIMCO-DELEGACION.md	Limites en delegacion
SIMCO-SUBAGENTE.md	Protocolo para subagentes
SIMCO-CCA-SUBAGENTE.md	CCA ligero para subagentes
CHECKLIST-PRE-DELEGACION.md	Checklist obligatorio
CONTEXT-MAP.yml	Presupuesto por proyecto
agents/perfiles/compact/	Perfiles compactos

---

Version: 1.1.0 | Sistema: SIMCO-NEXUS v4.0 | Tipo: Directiva de Control