theus-cli-linux-arm64 0.2.84

package/vendor/theus-arsenal/skills/aprendizaje-continuo-v2/agents/observer-loop.sh

@@ -0,0 +1,374 @@
+#!/usr/bin/env bash
+# Aprendizaje continuo v2 - Bucle en segundo plano del observador
+#
+# Incluye guarda de reentrada, regulación con cooldown y muestreo por cola
+# para evitar la explosión de memoria por procesos de análisis paralelos
+# descontrolados.
+
+set +e
+unset THEUSCODE
+
+SLEEP_PID=""
+USR1_FIRED=0
+PENDING_ANALYSIS=0
+ANALYZING=0
+LAST_ANALYSIS_EPOCH=0
+# Segundos mínimos entre análisis (evita re-disparos rápidos)
+ANALYSIS_COOLDOWN="${THEUS_OBSERVER_ANALYSIS_COOLDOWN:-60}"
+IDLE_TIMEOUT_SECONDS="${THEUS_OBSERVER_IDLE_TIMEOUT_SECONDS:-1800}"
+SESSION_LEASE_DIR="${PROJECT_DIR}/.observer-sessions"
+ACTIVITY_FILE="${PROJECT_DIR}/.observer-last-activity"
+
+# Resolver el directorio propio de este script para que los scripts hermanos
+# (session-guardian.sh) y los helpers relativos (../scripts/instinct-cli.py)
+# se resuelvan bien tanto si el archivo se ejecuta como si se carga con source.
+# $0 es el *llamador* cuando se hace source, así que se prefiere
+# ${BASH_SOURCE[0]}, que siempre apunta a este archivo.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+cleanup() {
+  [ -n "$SLEEP_PID" ] && kill "$SLEEP_PID" 2>/dev/null
+  if [ -f "$PID_FILE" ] && [ "$(cat "$PID_FILE" 2>/dev/null)" = "$$" ]; then
+    rm -f "$PID_FILE"
+  fi
+  exit 0
+}
+trap cleanup TERM INT
+
+file_mtime_epoch() {
+  local file="$1"
+  if [ ! -f "$file" ]; then
+    printf '0\n'
+    return
+  fi
+
+  if stat -c %Y "$file" >/dev/null 2>&1; then
+    stat -c %Y "$file" 2>/dev/null || printf '0\n'
+    return
+  fi
+
+  if stat -f %m "$file" >/dev/null 2>&1; then
+    stat -f %m "$file" 2>/dev/null || printf '0\n'
+    return
+  fi
+
+  printf '0\n'
+}
+
+has_active_session_leases() {
+  if [ ! -d "$SESSION_LEASE_DIR" ]; then
+    return 1
+  fi
+
+  find "$SESSION_LEASE_DIR" -type f -name '*.json' -print -quit 2>/dev/null | grep -q .
+}
+
+latest_activity_epoch() {
+  local observations_epoch activity_epoch
+  observations_epoch="$(file_mtime_epoch "$OBSERVATIONS_FILE")"
+  activity_epoch="$(file_mtime_epoch "$ACTIVITY_FILE")"
+
+  if [ "$activity_epoch" -gt "$observations_epoch" ] 2>/dev/null; then
+    printf '%s\n' "$activity_epoch"
+  else
+    printf '%s\n' "$observations_epoch"
+  fi
+}
+
+exit_if_idle_without_sessions() {
+  if has_active_session_leases; then
+    return
+  fi
+
+  local last_activity now_epoch idle_for
+  last_activity="$(latest_activity_epoch)"
+  now_epoch="$(date +%s)"
+  idle_for=$(( now_epoch - last_activity ))
+
+  if [ "$last_activity" -eq 0 ] || [ "$idle_for" -ge "$IDLE_TIMEOUT_SECONDS" ]; then
+    echo "[$(date)] Observador inactivo sin leases de sesión activos durante ${idle_for}s; saliendo" >> "$LOG_FILE"
+    cleanup
+  fi
+}
+
+wait_for_agent_analysis() {
+  local child_pid="$1"
+  local wait_status=0
+
+  while true; do
+    wait "$child_pid"
+    wait_status=$?
+
+    if [ "$wait_status" -eq 0 ]; then
+      return 0
+    fi
+
+    # SIGUSR1 puede interrumpir wait mientras el proceso hijo del análisis
+    # sigue corriendo. En ese caso se vuelve a esperar para no registrar una
+    # señal como un falso fallo del hijo.
+    if kill -0 "$child_pid" 2>/dev/null; then
+      continue
+    fi
+
+    return "$wait_status"
+  done
+}
+
+analyze_observations() {
+  if [ ! -f "$OBSERVATIONS_FILE" ]; then
+    return
+  fi
+
+  obs_count=$(wc -l < "$OBSERVATIONS_FILE" 2>/dev/null || echo 0)
+  if [ "$obs_count" -lt "$MIN_OBSERVATIONS" ]; then
+    return
+  fi
+
+  echo "[$(date)] Analizando $obs_count observaciones del proyecto ${PROJECT_NAME}..." >> "$LOG_FILE"
+
+  if [ "${ACV2_IS_WINDOWS:-false}" = "true" ] && [ "${THEUS_OBSERVER_ALLOW_WINDOWS:-false}" != "true" ]; then
+    echo "[$(date)] Se omite el análisis en Windows por un problema conocido de cuelgue no interactivo. Define THEUS_OBSERVER_ALLOW_WINDOWS=true para forzarlo." >> "$LOG_FILE"
+    return
+  fi
+
+  if ! command -v theus >/dev/null 2>&1; then
+    echo "[$(date)] No se encontró el CLI de theus; se omite el análisis" >> "$LOG_FILE"
+    return
+  fi
+
+  # session-guardian: regula el ciclo del observador (horas activas, cooldown, detección de inactividad)
+  if ! bash "${SCRIPT_DIR}/session-guardian.sh"; then
+    echo "[$(date)] Ciclo del observador omitido por session-guardian" >> "$LOG_FILE"
+    return
+  fi
+
+  # Muestrear las observaciones recientes en lugar de cargar el archivo entero.
+  # Esto evita pasar payloads de varios MB al modelo.
+  MAX_ANALYSIS_LINES="${THEUS_OBSERVER_MAX_ANALYSIS_LINES:-500}"
+  observer_tmp_dir="${PROJECT_DIR}/.observer-tmp"
+  mkdir -p "$observer_tmp_dir"
+  # Mantener la corrida XXXXXX al final de la plantilla: el mktemp de BSD/macOS
+  # solo sustituye una corrida final de X, así que un sufijo después (p. ej.
+  # `.jsonl`) produce un nombre literal no aleatorio que atasca todos los ciclos
+  # posteriores con "File exists".
+  analysis_file="$(mktemp "${observer_tmp_dir}/arsenal-observer-analysis.jsonl.XXXXXX")"
+  tail -n "$MAX_ANALYSIS_LINES" "$OBSERVATIONS_FILE" > "$analysis_file"
+  analysis_count=$(wc -l < "$analysis_file" 2>/dev/null || echo 0)
+  echo "[$(date)] Se usan las últimas $analysis_count de $obs_count observaciones para el análisis" >> "$LOG_FILE"
+
+  # Usar una ruta relativa a PROJECT_DIR por compatibilidad multiplataforma.
+  # En Windows (Git Bash/MSYS2), las rutas absolutas de mktemp pueden usar
+  # prefijos estilo MSYS (p. ej. /c/Users/...) que el subproceso del agente
+  # no puede resolver.
+  analysis_relpath=".observer-tmp/$(basename "$analysis_file")"
+
+  prompt_file="$(mktemp "${observer_tmp_dir}/arsenal-observer-prompt.XXXXXX")"
+  cat > "$prompt_file" <<PROMPT
+IMPORTANTE: Estás corriendo en modo --print no interactivo. DEBES usar la herramienta Write directamente para crear archivos. NO pidas permiso, NO pidas confirmación, NO devuelvas resúmenes en lugar de escribir. Solo lee, analiza y escribe.
+
+Lee ${analysis_relpath} e identifica patrones para el proyecto ${PROJECT_NAME} (correcciones del usuario, resoluciones de errores, flujos repetidos, preferencias de herramientas).
+Si encuentras 3+ ocurrencias del mismo patrón, DEBES escribir un archivo de instinto directamente en ${INSTINCTS_DIR}/<id>.md usando la herramienta Write.
+NO pidas permiso para escribir archivos, NO describas lo que escribirías y NO te quedes en el análisis cuando exista un patrón que califica.
+
+CRÍTICO: Todo archivo de instinto DEBE usar exactamente este formato:
+
+---
+id: nombre-en-kebab-case
+trigger: cuando <condición específica>
+confidence: <0.3-0.85 según frecuencia: 3-5 veces=0.5, 6-10=0.7, 11+=0.85>
+domain: <uno de: code-style, testing, git, debugging, workflow, file-patterns>
+source: session-observation
+scope: project
+project_id: ${PROJECT_ID}
+project_name: ${PROJECT_NAME}
+---
+
+# Título
+
+## Action
+<qué hacer, en una frase clara>
+
+## Evidence
+- Observado N veces en la sesión <id>
+- Patrón: <descripción>
+- Última observación: <fecha>
+
+Reglas:
+- Sé conservador: solo patrones claros con 3+ observaciones
+- Usa disparadores estrechos y específicos
+- Nunca incluyas fragmentos de código reales; describe solo los patrones
+- Cuando exista un patrón que califica, escribe o actualiza el archivo de instinto en esta ejecución en lugar de pedir confirmación
+- Si ya existe un instinto similar en ${INSTINCTS_DIR}/, actualízalo en lugar de crear un duplicado
+- El frontmatter YAML (entre marcadores ---) con el campo id es OBLIGATORIO
+- Si un patrón parece universal (no específico del proyecto), usa scope global en vez de project
+- Ejemplos de patrones globales: validar siempre la entrada del usuario, preferir manejo de errores explícito
+- Ejemplos de patrones de proyecto: usar componentes funcionales de React, seguir las convenciones de Django REST framework
+PROMPT
+
+  # Leer el prompt a memoria antes de lanzar el subproceso del agente.
+  # En Windows/MSYS2, la ruta de mktemp puede diferir de la resolución de rutas
+  # posterior del shell, así que apoyarse en cat "$prompt_file" dentro de la
+  # invocación puede fallar aunque el archivo se haya creado bien.
+  prompt_content="$(cat "$prompt_file" 2>/dev/null || true)"
+  rm -f "$prompt_file"
+  if [ -z "$prompt_content" ]; then
+    echo "[$(date)] No se pudo cargar el contenido del prompt del observador; se omite el análisis" >> "$LOG_FILE"
+    rm -f "$analysis_file"
+    return
+  fi
+
+  timeout_seconds="${THEUS_OBSERVER_TIMEOUT_SECONDS:-120}"
+  # Autoescalar max_turns en proporción al tamaño del lote cuando no se define
+  # explícitamente. Un valor fijo de 20 es insuficiente para el valor por
+  # defecto de 500 líneas de MAX_ANALYSIS_LINES: el agente agota --max-turns
+  # antes de poder escribir todos los archivos de instinto descubiertos.
+  # Fórmula: 1 turno por cada 10 líneas de análisis, mínimo 20, tope 100.
+  if [ -n "${THEUS_OBSERVER_MAX_TURNS:-}" ]; then
+    max_turns="${THEUS_OBSERVER_MAX_TURNS}"
+  else
+    max_turns=$(( analysis_count / 10 ))
+    if [ "$max_turns" -lt 20 ]; then max_turns=20; fi
+    if [ "$max_turns" -gt 100 ]; then max_turns=100; fi
+  fi
+  exit_code=0
+
+  # Sanear max_turns. La ruta autoescalada de arriba siempre da un valor válido
+  # >=20, pero un override explícito de THEUS_OBSERVER_MAX_TURNS puede ser no
+  # numérico, vacío o demasiado pequeño; aquí se protege y se cae al valor
+  # seguro de 20.
+  case "$max_turns" in
+    ''|*[!0-9]*)
+      max_turns=20
+      ;;
+  esac
+
+  if [ "$max_turns" -lt 4 ]; then
+    max_turns=20
+  fi
+
+  # Asegurar que el CWD sea PROJECT_DIR para que la ruta relativa
+  # analysis_relpath se resuelva bien en todas las plataformas, no solo cuando
+  # el observador se lanzó desde la raíz del proyecto.
+  cd "$PROJECT_DIR" || { echo "[$(date)] No se pudo hacer cd a PROJECT_DIR ($PROJECT_DIR); se omite el análisis" >> "$LOG_FILE"; rm -f "$analysis_file"; return; }
+
+  # Evitar que observe.sh registre esta sesión automatizada del observador
+  # como observaciones. El prompt se pasa con -p en lugar de redirigir stdin,
+  # por compatibilidad con Windows. prompt_content ya está en memoria, así que
+  # esto no depende de que la ruta absoluta de mktemp siga resolviéndose tras
+  # cambiar de cwd.
+  # El modelo es configurable vía THEUS_OBSERVER_MODEL; si no se define, el CLI
+  # usa su modelo por defecto. Los modelos más pesados son más lentos —
+  # considera subir THEUS_OBSERVER_TIMEOUT_SECONDS (120 s por defecto) para que
+  # el watchdog no mate el análisis a medias.
+  observer_model_args=()
+  if [ -n "${THEUS_OBSERVER_MODEL:-}" ]; then
+    observer_model_args=(--model "${THEUS_OBSERVER_MODEL}")
+  fi
+  THEUS_SKIP_OBSERVE=1 THEUS_HOOK_PROFILE=minimal theus "${observer_model_args[@]}" --max-turns "$max_turns" --print \
+    --allowedTools "Read,Write" \
+    -p "$prompt_content" >> "$LOG_FILE" 2>&1 &
+  agent_pid=$!
+
+  (
+    sleep "$timeout_seconds"
+    if kill -0 "$agent_pid" 2>/dev/null; then
+      echo "[$(date)] El análisis del agente superó los ${timeout_seconds}s; terminando el proceso" >> "$LOG_FILE"
+      kill "$agent_pid" 2>/dev/null || true
+    fi
+  ) &
+  watchdog_pid=$!
+
+  wait_for_agent_analysis "$agent_pid"
+  exit_code=$?
+  kill "$watchdog_pid" 2>/dev/null || true
+  rm -f "$analysis_file"
+
+  if [ "$exit_code" -ne 0 ]; then
+    echo "[$(date)] El análisis del agente falló (exit $exit_code); se conservan las observaciones para reintentar" >> "$LOG_FILE"
+    return
+  fi
+
+  # Archivar las observaciones solo tras un análisis exitoso. Un fallo
+  # transitorio (timeout, salida distinta de cero, límite de tasa) no debe
+  # descartar el lote antes de convertirse en instintos, ya que el analizador
+  # solo lee el archivo de observaciones vivo.
+  if [ -f "$OBSERVATIONS_FILE" ]; then
+    archive_dir="${PROJECT_DIR}/observations.archive"
+    mkdir -p "$archive_dir"
+    mv "$OBSERVATIONS_FILE" "$archive_dir/processed-$(date +%Y%m%d-%H%M%S)-$$.jsonl" 2>/dev/null || true
+  fi
+}
+
+on_usr1() {
+  [ -n "$SLEEP_PID" ] && kill "$SLEEP_PID" 2>/dev/null
+  SLEEP_PID=""
+
+  # Guarda de reentrada: diferir el aviso para que el bucle principal ejecute
+  # un análisis de seguimiento justo al terminar el análisis en curso.
+  if [ "$ANALYZING" -eq 1 ]; then
+    PENDING_ANALYSIS=1
+    echo "[$(date)] Análisis ya en curso; se difiere la señal" >> "$LOG_FILE"
+    return
+  fi
+
+  USR1_FIRED=1
+
+  # Cooldown: omitir si el último análisis fue demasiado reciente
+  now_epoch=$(date +%s)
+  elapsed=$(( now_epoch - LAST_ANALYSIS_EPOCH ))
+  if [ "$elapsed" -lt "$ANALYSIS_COOLDOWN" ]; then
+    echo "[$(date)] Cooldown de análisis activo (${elapsed}s < ${ANALYSIS_COOLDOWN}s); se omite" >> "$LOG_FILE"
+    return
+  fi
+
+  ANALYZING=1
+  analyze_observations
+  LAST_ANALYSIS_EPOCH=$(date +%s)
+  ANALYZING=0
+}
+trap on_usr1 USR1
+
+# Cuando este archivo se carga con source (p. ej. desde tests) en lugar de
+# ejecutarse, se detiene aquí para que quien llama pueda invocar funciones
+# individuales como analyze_observations sin iniciar el bucle del observador.
+# El único llamador de producción (start-observer.sh) ejecuta el script, así
+# que allí $0 es igual a BASH_SOURCE[0] y esta guarda no hace nada.
+if [ "${BASH_SOURCE[0]}" != "${0}" ]; then
+  return 0 2>/dev/null || true
+fi
+
+echo "$$" > "$PID_FILE"
+echo "[$(date)] Observador iniciado para ${PROJECT_NAME} (PID: $$)" >> "$LOG_FILE"
+
+# Podar los instintos pendientes caducados antes del análisis (SCRIPT_DIR se
+# resolvió arriba con ${BASH_SOURCE[0]}, correcto tanto en ejecución como en source).
+"${ACV2_PYTHON_CMD:-python3}" "${SCRIPT_DIR}/../scripts/instinct-cli.py" prune --quiet >> "$LOG_FILE" 2>&1 || echo "[$(date)] Aviso: falló la poda de instintos (no fatal)" >> "$LOG_FILE"
+
+while true; do
+  exit_if_idle_without_sessions
+
+  if [ "$PENDING_ANALYSIS" -eq 1 ]; then
+    PENDING_ANALYSIS=0
+    USR1_FIRED=0
+    ANALYZING=1
+    analyze_observations
+    LAST_ANALYSIS_EPOCH=$(date +%s)
+    ANALYZING=0
+    continue
+  fi
+
+  sleep "$OBSERVER_INTERVAL_SECONDS" &
+  SLEEP_PID=$!
+  wait "$SLEEP_PID" 2>/dev/null
+  SLEEP_PID=""
+
+  exit_if_idle_without_sessions
+  if [ "$USR1_FIRED" -eq 1 ]; then
+    USR1_FIRED=0
+  else
+    ANALYZING=1
+    analyze_observations
+    LAST_ANALYSIS_EPOCH=$(date +%s)
+    ANALYZING=0
+  fi
+done

package/vendor/theus-arsenal/skills/aprendizaje-continuo-v2/agents/observer.md

@@ -0,0 +1,188 @@
+---
+name: observer
+description: Agente en segundo plano que analiza las observaciones de sesión para detectar patrones y crear instintos. Usa un modelo económico para reducir costos. La v2.1 añade instintos con ámbito de proyecto.
+---
+
+# Agente observador
+
+Un agente en segundo plano que analiza las observaciones de las sesiones del CLI para detectar patrones y crear instintos.
+
+## Cuándo se ejecuta
+
+- Cuando se acumulan suficientes observaciones (configurable, por defecto 20)
+- En un intervalo programado (configurable, por defecto 5 minutos)
+- Bajo demanda, mediante SIGUSR1 al proceso observador
+
+## Entrada
+
+Lee las observaciones del archivo de observaciones **con ámbito de proyecto**:
+- Proyecto: `~/.theus/arsenal/projects/<hash-proyecto>/observations.jsonl`
+- Fallback global: `~/.theus/arsenal/observations.jsonl`
+
+```jsonl
+{"timestamp":"2025-01-22T10:30:00Z","event":"tool_start","session":"abc123","tool":"Edit","input":"...","project_id":"a1b2c3d4e5f6","project_name":"mi-app-react"}
+{"timestamp":"2025-01-22T10:30:01Z","event":"tool_complete","session":"abc123","tool":"Edit","output":"...","project_id":"a1b2c3d4e5f6","project_name":"mi-app-react"}
+{"timestamp":"2025-01-22T10:30:05Z","event":"tool_start","session":"abc123","tool":"Bash","input":"npm test","project_id":"a1b2c3d4e5f6","project_name":"mi-app-react"}
+{"timestamp":"2025-01-22T10:30:10Z","event":"tool_complete","session":"abc123","tool":"Bash","output":"Todos los tests pasan","project_id":"a1b2c3d4e5f6","project_name":"mi-app-react"}
+```
+
+## Detección de patrones
+
+Busca estos patrones en las observaciones:
+
+### 1. Correcciones del usuario
+Cuando un mensaje posterior del usuario corrige la acción previa del agente:
+- "No, usa X en vez de Y"
+- "En realidad quería decir…"
+- Patrones inmediatos de deshacer/rehacer
+
+→ Crear instinto: "Al hacer X, prefiere Y"
+
+### 2. Resoluciones de errores
+Cuando a un error le sigue una corrección:
+- La salida de la herramienta contiene un error
+- Las siguientes llamadas a herramientas lo arreglan
+- El mismo tipo de error se resuelve igual varias veces
+
+→ Crear instinto: "Al encontrar el error X, prueba Y"
+
+### 3. Flujos de trabajo repetidos
+Cuando la misma secuencia de herramientas se usa varias veces:
+- Misma secuencia de herramientas con entradas similares
+- Patrones de archivos que cambian juntos
+- Operaciones agrupadas en el tiempo
+
+→ Crear instinto de flujo: "Al hacer X, sigue los pasos Y, Z, W"
+
+### 4. Preferencias de herramientas
+Cuando ciertas herramientas se prefieren de forma consistente:
+- Siempre usa Grep antes de Edit
+- Prefiere Read a `cat` en Bash
+- Usa comandos Bash específicos para ciertas tareas
+
+→ Crear instinto: "Al necesitar X, usa la herramienta Y"
+
+## Salida
+
+Crea/actualiza instintos en el directorio de instintos **con ámbito de proyecto**:
+- Proyecto: `~/.theus/arsenal/projects/<hash-proyecto>/instincts/personal/`
+- Global: `~/.theus/arsenal/instincts/personal/` (para patrones universales)
+
+### Instinto con ámbito de proyecto (por defecto)
+
+```yaml
+---
+id: use-react-hooks-pattern
+trigger: "al crear componentes React"
+confidence: 0.65
+domain: "code-style"
+source: "session-observation"
+scope: project
+project_id: "a1b2c3d4e5f6"
+project_name: "mi-app-react"
+---
+
+# Usar el patrón de hooks de React
+
+## Action
+Usar siempre componentes funcionales con hooks en lugar de componentes de clase.
+
+## Evidence
+- Observado 8 veces en la sesión abc123
+- Patrón: todos los componentes nuevos usan useState/useEffect
+- Última observación: 2025-01-22
+```
+
+### Instinto global (patrones universales)
+
+```yaml
+---
+id: always-validate-user-input
+trigger: "al manejar entrada del usuario"
+confidence: 0.75
+domain: "security"
+source: "session-observation"
+scope: global
+---
+
+# Validar siempre la entrada del usuario
+
+## Action
+Validar y sanear toda entrada del usuario antes de procesarla.
+
+## Evidence
+- Observado en 3 proyectos distintos
+- Patrón: el usuario añade validación de entrada de forma consistente
+- Última observación: 2025-01-22
+```
+
+## Guía de decisión de ámbito
+
+Al crear instintos, determina el ámbito según estas heurísticas:
+
+> **Guía de decisión de ámbito** — consulta la tabla canónica bajo el encabezado "Guía de decisión de ámbito" en el `SKILL.md` de `aprendizaje-continuo-v2`.
+
+**Ante la duda, usa `scope: project` por defecto** — es más seguro ser específico del proyecto y promover después que contaminar el espacio global.
+
+## Cálculo de confianza
+
+Confianza inicial según la frecuencia de observación:
+- 1-2 observaciones: 0.3 (tentativo)
+- 3-5 observaciones: 0.5 (moderado)
+- 6-10 observaciones: 0.7 (fuerte)
+- 11+ observaciones: 0.85 (muy fuerte)
+
+La confianza se ajusta con el tiempo:
+- +0.05 por cada observación que confirma
+- -0.1 por cada observación que contradice
+- -0.02 por semana sin observaciones (decaimiento)
+
+## Promoción de instintos (proyecto → global)
+
+Un instinto debe promoverse de ámbito de proyecto a global cuando:
+1. El **mismo patrón** (por id o disparador similar) existe en **2+ proyectos distintos**
+2. La confianza media entre instancias es **>= 0.8**
+3. El dominio está en la lista apta para global (security, general-best-practices, workflow)
+
+La promoción la gestiona el comando `instinct-cli.py promote` o el análisis de `/evolucionar`.
+
+## Directrices importantes
+
+1. **Sé conservador**: crea instintos solo para patrones claros (3+ observaciones)
+2. **Sé específico**: los disparadores estrechos son mejores que los amplios
+3. **Registra la evidencia**: incluye siempre qué observaciones originaron el instinto
+4. **Respeta la privacidad**: nunca incluyas fragmentos de código reales, solo patrones
+5. **Fusiona lo similar**: si un instinto nuevo se parece a uno existente, actualízalo en vez de duplicarlo
+6. **Ámbito de proyecto por defecto**: salvo que el patrón sea claramente universal, hazlo de ámbito de proyecto
+7. **Incluye el contexto del proyecto**: define siempre `project_id` y `project_name` en los instintos de proyecto
+
+## Sesión de análisis de ejemplo
+
+Dadas las observaciones:
+```jsonl
+{"event":"tool_start","tool":"Grep","input":"pattern: useState","project_id":"a1b2c3","project_name":"mi-app"}
+{"event":"tool_complete","tool":"Grep","output":"Encontrado en 3 archivos","project_id":"a1b2c3","project_name":"mi-app"}
+{"event":"tool_start","tool":"Read","input":"src/hooks/useAuth.ts","project_id":"a1b2c3","project_name":"mi-app"}
+{"event":"tool_complete","tool":"Read","output":"[contenido del archivo]","project_id":"a1b2c3","project_name":"mi-app"}
+{"event":"tool_start","tool":"Edit","input":"src/hooks/useAuth.ts...","project_id":"a1b2c3","project_name":"mi-app"}
+```
+
+Análisis:
+- Flujo detectado: Grep → Read → Edit
+- Frecuencia: visto 5 veces en esta sesión
+- **Decisión de ámbito**: es un patrón de flujo general (no específico del proyecto) → **global**
+- Crear instinto:
+  - trigger: "al modificar código"
+  - action: "Buscar con Grep, confirmar con Read y después Edit"
+  - confidence: 0.6
+  - domain: "workflow"
+  - scope: "global"
+
+## Integración con el generador de skills
+
+Cuando los instintos se importan desde un análisis de repositorio, traen:
+- `source: "repo-analysis"`
+- `source_repo: "https://..."`
+- `scope: "project"` (porque provienen de un repo concreto)
+
+Deben tratarse como convenciones de equipo/proyecto con confianza inicial más alta (0.7+).