Capa de Inteligencia — Los 4 Pilares

Cómo Arc OS valida, aprende, enfoca y se mejora a sí mismo.

Resumen

La Capa de Inteligencia se sitúa entre los mensajes del usuario y las respuestas de Claude. Opera en cuatro etapas:

         INPUT                    PROCESSING                 OUTPUT
    ┌──────────────┐        ┌──────────────────┐       ┌─────────────────┐
    │ User Message  │───────►│  Context Router   │       │ Claude Response  │
    │               │        │  (skill scoring)  │       │  + eval warnings │
    │ Fix It / 👎   │        │                  │       │                 │
    │ (feedback)    │        │  Learnings       │       │ Quality metrics │
    │               │        │  (correction     │       │  logged         │
    └──────────────┘        │   injection)     │       └────────┬────────┘
                            │                  │                │
                            │  buildGsdPrompt()│        ┌───────┴────────┐
                            └────────┬─────────┘        │ Nightly Loop   │
                                     │                  │ (improvement   │
                                     ▼                  │  proposals)    │
                              Claude CLI                └────────────────┘

Pilar 1: Motor de Evals Binarios

Qué: Reglas declarativas que verifican cada respuesta antes de entregarla.

Por qué: El output de IA debería tener controles de calidad, como los tests unitarios para el código.

Cómo:

Cada skill puede tener un archivo .evals.json con reglas:

{
  "rules": [
    { "id": "gm-001", "type": "string_not_contains", "value": "--force", "severity": "warning" },
    { "id": "gm-002", "type": "max_length", "value": 4000, "severity": "info" }
  ]
}

Después de que Claude genera una respuesta, el motor de evals ejecuta todas las reglas aplicables:

Pasa: la respuesta se entrega tal cual
Falla: la respuesta se entrega + se añade una nota de advertencia al pie

[Claude's response about git operations]
---
Eval: ⚠️ No force push | ℹ️ Response under 4000 chars

Tipos de Reglas

Tipo	Qué Verifica
`string_contains`	La respuesta debe incluir texto literal
`string_not_contains`	La respuesta NO debe incluir texto
`regex_match`	La respuesta debe coincidir con el patrón regex
`regex_not_match`	La respuesta NO debe coincidir con el regex
`max_length`	La respuesta debe ser <= N caracteres
`min_length`	La respuesta debe ser >= N caracteres

Decisiones Clave de Diseño

No bloqueante: Las advertencias no suprimen las respuestas. El usuario ve tanto la respuesta como la observación.
Por skill: Cada skill tiene criterios de calidad distintos.
Por proyecto: El mismo skill puede tener reglas diferentes según el stack tecnológico.
Sin IA en la validación: Las reglas son deterministas. Pasa o falla de forma binaria. Sin ambigüedad.

Referencia de diseño: Anthropic Skill Creator — evals estructurados con afirmaciones binarias.

Pilar 2: Context Router

Qué: Selección inteligente de skills que inyecta solo los más relevantes en cada prompt.

Por qué: 25 skills cargados a la vez = dilución de contexto. El modelo intenta aplicar consejos de despliegue a revisiones de código.

Cómo:

Antes de construir el prompt, el router puntúa cada skill registrado contra el mensaje del usuario:

Score = (trigger matches x 2) + (keyword matches x 1)
Sort by score descending → take top 5

Ejemplo:

User: "Review this code for XSS vulnerabilities"

Scoring:
  code-review:     trigger "review" (2) + keyword "XSS" (1) = 3
  code-review-protocol: trigger "code review" (2)            = 2
  deployment-flow: no match                                  = 0
  git-manager:     no match                                  = 0

Injected into prompt:
  SKILLS_HINT (focus on these):
  - code-review: Security audit and code quality review...
  - code-review-protocol: Structured code review with OWASP...

Por Qué Sugerencias en Lugar de Filtrado

El router sugiere skills pero no bloquea otros. Claude sigue teniendo acceso completo.

Enfoque	Riesgo
Filtrado estricto (`--allowedTools`)	Una clasificación errónea rompe la sesión
Mutaciones de symlinks	Cambios en el sistema de archivos sobre un proceso en ejecución
Sugerencias orientativas	Seguro: una sugerencia incorrecta = Claude la ignora

Triggers vs Keywords

Triggers (2 pts): Señales de invocación explícita. El usuario solicita directamente esta capacidad.

"deploy", "review", "scaffold", "audit"

Keywords (1 pt): Contexto semántico más amplio. Sugiere relevancia sin ser un comando.

"OWASP", "Docker", "CI/CD", "performance"

Referencia de diseño: Priming de contexto — atención enfocada sin filtrado estricto.

Pilar 3: Reflect Loop

Qué: Captura automática de correcciones como reglas persistentes.

Por qué: Las correcciones a la IA deben sobrevivir a los reinicios. Una corrección = mejora permanente.

Cómo:

CEO presses 🛠️ Fix It
    │
    ├── addLearning(source: "fixit", rule: "Fix requested for: <last response>")
    ├── projectLearnings reloaded from disk
    └── Fix prompt sent to Claude for immediate correction

CEO presses 👎
    │
    ├── addLearning(source: "negative", rule: "Negative feedback on: <response>")
    ├── qualityTracker.logFeedback(positive: false)
    └── projectLearnings reloaded from disk

Las reglas se guardan en learnings.md:

# Learnings

## Rules

- [2026-04-03T14:22:00Z] [fixit] Always use t-call for translations in Odoo QWeb
- [2026-04-03T15:10:00Z] [negative] Avoid sudo in deployment scripts

En cada mensaje posterior, los logs acumulados se inyectan:

LEARNINGS (past corrections — follow these rules):
- Avoid sudo in deployment scripts
- Always use t-call for translations in Odoo QWeb

Propiedades Clave

Automático: Sin escritura manual de reglas. Presiona un botón → regla creada.
Persistente: Sobrevive a reinicios del bot. Se escribe en disco como Markdown.
Por proyecto: Cada Child Bot tiene su propio learnings.md. Las correcciones de Odoo no afectan al bot de React.
Más reciente primero: Las correcciones más recientes tienen mayor visibilidad en el prompt.
Con límite: Máximo 2000 caracteres en el bloque LEARNINGS. Las reglas más antiguas se descartan.

Referencia de diseño: Claude Reflect System — las correcciones se convierten en reglas permanentes que previenen regresiones.

Pilar 4: Karpathy Loop

Qué: Análisis automatizado nocturno de métricas de calidad con propuestas de mejora enviadas al CEO.

Por qué: Los humanos olvidan revisar el rendimiento. El sistema debería encontrar sus propios puntos débiles.

Cómo:

Cada día a las 03:00 UTC, scripts/nightly-improve.ts se ejecuta:

Leer el registro — enumerar todos los Child Bots desde bot_registry.json
Leer métricas — cargar quality-metrics.json por cada child
Encontrar los de bajo rendimiento — filtrar skills donde:
- applied_count >= 3 (tamaño mínimo de muestra para evitar ruido)
- Y además success_rate < 80% O feedback_negative > feedback_positive
Leer logs — extraer patrones de corrección relacionados
Generar propuestas — basadas en plantillas (deterministas, sin IA)
Enviar al CEO — informe resumen + tarjetas de propuestas individuales en Telegram

Flujo de Aprobación del CEO

Telegram: Proposal Card
┌──────────────────────────────────────┐
│ Improvement Proposal                  │
│                                       │
│ Child: citadel-v2                     │
│ Skill: code-review                    │
│ Reason: low success rate (72%)        │
│ Feedback: 👍 4 / 👎 6                │
│                                       │
│ Related learnings:                    │
│   • Always use t-call for i18n        │
│                                       │
│ [✅ Approve]  [❌ Reject]             │
└──────────────────────────────────────┘

Aprobar: Copia de seguridad skill.md → skill.v1.md (máx. 3 versiones). Marcar como aprobado.
Rechazar: Marcar como rechazado en proposals.json. Sin cambios realizados.

Decisiones Clave de Diseño

Propuestas basadas en plantillas: Ninguna IA genera las mejoras. El sistema identifica el problema; el humano decide la solución.
CEO en el bucle: Sin reescritura autónoma de skills. Se requiere una aprobación con un toque.
Versionado de skills: Las copias de seguridad previenen la pérdida de datos. Máximo 3 versiones por skill.
Tamaño mínimo de muestra: Los skills con menos de 3 usos se excluyen del análisis (para evitar falsos positivos).

Referencia de diseño: Karpathy AutoResearch Loop — modificar → verificar → conservar/descartar → repetir. Con la incorporación crítica de la aprobación humana.

Cómo Trabajan Juntos los 4 Pilares

Day 1:
  CEO sends message → Context Router suggests relevant skills
  Claude responds → Evals check output → Warning: "No force push"
  CEO sees warning, presses Fix It → Learning saved to learnings.md

Day 2:
  CEO sends similar message → Learnings injected: "Don't use --force"
  Claude avoids the mistake → No eval warnings → thumbs-up
  Quality metrics improve for that skill

Day 30:
  Nightly loop detects git-manager skill has 95% success rate
  No proposal needed — skill is healthy

Day 30 (different skill):
  Nightly loop detects code-review at 68% success
  Sends proposal to CEO → CEO approves → skill backed up
  CEO manually improves skill.md
  Next cycle: success rate climbs

El sistema crea un bucle de retroalimentación positiva: las correcciones se convierten en reglas persistentes → las reglas mejoran la calidad → las métricas reflejan la mejora → el bucle nocturno confirma el buen estado del sistema.

Pilar 5: Sage Worker (Phase 40.11+)

Qué: Análisis de skills potenciado por IA, benchmarking y descubrimiento en el marketplace.

Por qué: La mejora manual de skills no escala. Se necesita un análisis automatizado de la calidad de los skills y acceso a la experiencia de la comunidad.

Cómo:

Análisis de Skills

Selecciona cualquier skill en la UI de Skill Evolution → haz clic en "Sage Analyze" → Sage (Claude Haiku) evalúa:

Claridad y completitud de las instrucciones del skill
Cobertura de reglas de eval
Recomendaciones de mejora

Benchmarks A/B

Compara dos versiones de un skill:

Selecciona una actualización de skill (PR)
Ejecuta el benchmark → Sage prueba ambas versiones contra prompts de muestra
Los resultados muestran una comparación de calidad con resumen

Descubrimiento en el Marketplace

Busca skills creados por la comunidad en claudemarketplaces.com:

"Sage Scout" → busca por palabra clave
Analiza la compatibilidad con tu proyecto
Instala de forma global o haz fork a un proyecto específico

Referencia de diseño: Gestores de paquetes (npm, pip) para la gestión de skills de IA, con análisis de compatibilidad potenciado por LLM.