# Instintos del Proyecto — SWL-SES
# Generado automáticamente por scripts/bootstrap-instintos.js desde .planning/APRENDIZAJES.md
# Formato estandarizado v1.0

version: "1.0"
generado: "2026-04-19"
total_instintos: 26

instintos:
  - id: inst-001
    pattern: "Heurística de paralelización del orquestador"
    description: "Paralelizar (múltiples Agent() en un solo mensaje) cuando las tareas son independientes y no comparten archivos. Ir secuencial cuando hay dependencias de datos entre agentes."
    confidence: 0.8
    scope: project
    source: "APRENDIZAJES.md"
    evidence_count: 1
    last_validated: "2026-03-29"
    contradictions: 0
    status: active
    tags: ["decision", "arquitectura"]
    created_at: "2026-04-19"
    seccion_origen: "Decisiones de arquitectura"

  - id: inst-002
    pattern: "Pipeline mobile"
    description: "producto-prd-swl → mobile-cross-swl (decisión) → mobile-android/ios-swl → tdd-qa-swl. La decisión de framework (React Native vs Flutter vs nativo) se toma en mobile-cross-swl, no en el orquestador."
    confidence: 0.8
    scope: project
    source: "APRENDIZAJES.md"
    evidence_count: 1
    last_validated: "2026-03-29"
    contradictions: 0
    status: active
    tags: ["decision", "arquitectura"]
    created_at: "2026-04-19"
    seccion_origen: "Decisiones de arquitectura"

  - id: inst-003
    pattern: "Fragmentación de criterio en CLAUDE.md"
    description: "Con 53 agentes compartiendo el mismo CLAUDE.md, las reglas deben ser genéricas o explícitamente marcadas con su alcance. Una regla de Angular escrita genéricamente confunde al agente de backend."
    confidence: 0.8
    scope: project
    source: "APRENDIZAJES.md"
    evidence_count: 1
    last_validated: "2026-03-29"
    contradictions: 0
    status: active
    tags: ["decision", "arquitectura"]
    created_at: "2026-04-19"
    seccion_origen: "Decisiones de arquitectura"

  - id: inst-004
    pattern: "Preservación de evoluciones en actualización"
    description: "`decideUpdateStrategy()` debe usar `evolvedFrom <= versionNueva` (no igualdad exacta) para preservar evoluciones de versiones anteriores. Tres bugs en cadena descubiertos y corregidos."
    confidence: 0.8
    scope: project
    source: "APRENDIZAJES.md"
    evidence_count: 1
    last_validated: "2026-04-02"
    contradictions: 0
    status: active
    tags: ["decision", "arquitectura"]
    created_at: "2026-04-19"
    seccion_origen: "Decisiones de arquitectura"

  - id: inst-005
    pattern: "CLAUDE.md lean reduce 77% de tokens por turno"
    description: "Mover tablas de inventario detalladas a INVENTARIO.md y mantener CLAUDE.md como índice compacto ahorra ~4,585 tokens/turno sin perder funcionalidad."
    confidence: 0.8
    scope: project
    source: "APRENDIZAJES.md"
    evidence_count: 1
    last_validated: "2026-04-03"
    contradictions: 0
    status: active
    tags: ["decision", "arquitectura"]
    created_at: "2026-04-19"
    seccion_origen: "Decisiones de arquitectura"

  - id: inst-006
    pattern: "Detección automática de stack tecnológico"
    description: "`detectarTecnologias()` con 40+ patrones (packages, configFiles, configContent) alimenta agent-matcher y model-router para asignación automática de agentes y skills."
    confidence: 0.8
    scope: project
    source: "APRENDIZAJES.md"
    evidence_count: 1
    last_validated: "2026-04-06"
    contradictions: 0
    status: active
    tags: ["decision", "arquitectura"]
    created_at: "2026-04-19"
    seccion_origen: "Decisiones de arquitectura"

  - id: inst-007
    pattern: "stderr en hooks causa error en Claude Code"
    description: "Nunca escribir a stderr en hooks — Claude Code lo interpreta como error del hook. Usar stdout para mensajes y exit code 0 para advertencias, exit code 2 para bloqueos."
    confidence: 0.7
    scope: project
    source: "APRENDIZAJES.md"
    evidence_count: 1
    last_validated: "2026-04-01"
    contradictions: 0
    status: active
    tags: ["anti-patron"]
    created_at: "2026-04-19"
    seccion_origen: "Anti-patrones detectados"

  - id: inst-008
    pattern: "Hook que bloquea por error interno"
    description: "Todo hook debe envolver su lógica en try/catch y nunca bloquear por errores propios. Solo bloquear por violaciones reales de seguridad o calidad."
    confidence: 0.7
    scope: project
    source: "APRENDIZAJES.md"
    evidence_count: 1
    last_validated: "2026-04-01"
    contradictions: 0
    status: active
    tags: ["anti-patron"]
    created_at: "2026-04-19"
    seccion_origen: "Anti-patrones detectados"

  - id: inst-009
    pattern: "Archivos evolucionados sin marcar"
    description: "Si un agente, skill o comando es modificado por `/swl:aprender` o `/swl:evolucionar` sin `markAsEvolved()`, la próxima actualización lo sobreescribe. El marcado en frontmatter es obligatorio."
    confidence: 0.7
    scope: project
    source: "APRENDIZAJES.md"
    evidence_count: 1
    last_validated: "2026-04-02"
    contradictions: 0
    status: active
    tags: ["anti-patron"]
    created_at: "2026-04-19"
    seccion_origen: "Anti-patrones detectados"

  - id: inst-010
    pattern: "Agente debilita config de linter en vez de corregir código"
    description: "Proteger archivos de configuración (.eslintrc, tsconfig.json, .prettierrc, etc.) con advertencia que redirige a corregir el código fuente."
    confidence: 0.7
    scope: project
    source: "APRENDIZAJES.md"
    evidence_count: 1
    last_validated: "2026-04-06"
    contradictions: 0
    status: active
    tags: ["anti-patron"]
    created_at: "2026-04-19"
    seccion_origen: "Anti-patrones detectados"

  - id: inst-011
    pattern: "`.claude/settings.json` no se commitea — hooks deben auto-documentarse"
    description: "`.claude/` está en `.gitignore`. Al agregar hooks nuevos (PreCompact, SubagentStop, PostToolUseFailure), documentar los eventos y matchers esperados en los comentarios de cabecera del archivo `.js` del hook, para que otro desarrollador pueda reconstruir `settings.json` desde los fuentes."
    confidence: 0.7
    scope: project
    source: "APRENDIZAJES.md"
    evidence_count: 1
    last_validated: "2026-04-10"
    contradictions: 0
    status: active
    tags: ["anti-patron"]
    created_at: "2026-04-19"
    seccion_origen: "Anti-patrones detectados"

  - id: inst-012
    pattern: "Verificar existencia de skills antes de crear nuevos"
    description: "Antes de implementar un skill \"nuevo\", buscar con `glob` en `habilidades/` si ya existe. En la sesión v5.4.0, 4 de 5 componentes propuestos como nuevos ya existían con contenido completo (redis-experto, mongodb-experto, kubernetes-orquestacion, graphql-experto)."
    confidence: 0.7
    scope: project
    source: "APRENDIZAJES.md"
    evidence_count: 1
    last_validated: "2026-04-10"
    contradictions: 0
    status: active
    tags: ["anti-patron"]
    created_at: "2026-04-19"
    seccion_origen: "Anti-patrones detectados"

  - id: inst-013
    pattern: "Patrones SQLAlchemy async"
    description: "`selectinload()` obligatorio en toda relación accedida en serialización Pydantic. `lazy=\"selectin\"` para relaciones frecuentes. Services no hacen `db.commit()`."
    confidence: 0.6
    scope: project
    source: "APRENDIZAJES.md"
    evidence_count: 1
    last_validated: "2026-03-29"
    contradictions: 0
    status: active
    tags: ["patron"]
    created_at: "2026-04-19"
    seccion_origen: "Patrones exitosos"

  - id: inst-014
    pattern: "Circuit breaker en hooks"
    description: "Degradar hook automáticamente tras 3 fallos consecutivos, half-open recovery a los 5 minutos. Previene cascadas de fallos en sesiones largas."
    confidence: 0.6
    scope: project
    source: "APRENDIZAJES.md"
    evidence_count: 1
    last_validated: "2026-04-01"
    contradictions: 0
    status: active
    tags: ["patron"]
    created_at: "2026-04-19"
    seccion_origen: "Patrones exitosos"

  - id: inst-015
    pattern: "Auto-consolidación patrón autoDream"
    description: "Sugerir `/swl:aprender` cuando pasan >= 24h y >= 5 sesiones nuevas. Lock basado en mtime con staleness de 1h."
    confidence: 0.6
    scope: project
    source: "APRENDIZAJES.md"
    evidence_count: 1
    last_validated: "2026-04-02"
    contradictions: 0
    status: active
    tags: ["patron"]
    created_at: "2026-04-19"
    seccion_origen: "Patrones exitosos"

  - id: inst-016
    pattern: "toolBudget por agente"
    description: "Presupuesto de tool calls (simple/standard/complex) en el frontmatter. Los revisores con budget 10/20/35, los implementadores con 15/30/60. Evita desperdicio de tool calls en tareas simples."
    confidence: 0.6
    scope: project
    source: "APRENDIZAJES.md"
    evidence_count: 1
    last_validated: "2026-04-06"
    contradictions: 0
    status: active
    tags: ["patron"]
    created_at: "2026-04-19"
    seccion_origen: "Patrones exitosos"

  - id: inst-017
    pattern: "Write-complete-test-once para slices simples"
    description: "Para slices ≤3 archivos y ≤100 líneas: escribir solución completa y testear una sola vez al final. Solo iterar si el test falla. Reduce 40-60% de tool calls."
    confidence: 0.6
    scope: project
    source: "APRENDIZAJES.md"
    evidence_count: 1
    last_validated: "2026-04-06"
    contradictions: 0
    status: active
    tags: ["patron"]
    created_at: "2026-04-19"
    seccion_origen: "Patrones exitosos"

  - id: inst-018
    pattern: "Clasificación automática de mensajes del usuario"
    description: "Hook UserPromptSubmit con 9 categorías por regex español+inglés. Inyecta hints de routing sin bloquear ni modificar el mensaje. Costo ~0 en tokens de input."
    confidence: 0.6
    scope: project
    source: "APRENDIZAJES.md"
    evidence_count: 1
    last_validated: "2026-04-06"
    contradictions: 0
    status: active
    tags: ["patron"]
    created_at: "2026-04-19"
    seccion_origen: "Patrones exitosos"

  - id: inst-019
    pattern: "Filtro de dominio ANTES de analizar repos externos"
    description: "Aplicar el filtro de CLAUDE.md (\"¿le sirve a un ingeniero de software en cualquier proyecto?\") como primer paso al evaluar repos en `temp/`. Ahorra 100% del tiempo de análisis en repos incompatibles. Ejemplo: `awesome-design-systems-master` (lista curada de enlaces, sin código) se descartó en <30 segundos."
    confidence: 0.6
    scope: project
    source: "APRENDIZAJES.md"
    evidence_count: 1
    last_validated: "2026-04-10"
    contradictions: 0
    status: active
    tags: ["patron"]
    created_at: "2026-04-19"
    seccion_origen: "Patrones exitosos"

  - id: inst-020
    pattern: "`package-lock.json` retiene versión anterior tras bump [CONFIRMADO x2]"
    description: "La versión aparece en 2 ubicaciones (líneas 3 y 9). Se actualiza con `npm install`, no con sed. Si se edita manualmente, verificar AMBAS ubicaciones. Confirmado el 2026-04-10 durante bump v5.3.4→v5.4.0."
    confidence: 0.6
    scope: project
    source: "APRENDIZAJES.md"
    evidence_count: 1
    last_validated: "2026-04-02"
    contradictions: 0
    status: active
    tags: ["gotcha"]
    created_at: "2026-04-19"
    seccion_origen: "Gotchas del sistema"

  - id: inst-021
    pattern: "APRENDIZAJES.md se infla con contenido no-accionable [CONFIRMADO x2]"
    description: "El hook `extraccion-aprendizajes.js` captura fragmentos de código y documentación como \"aprendizajes\". Requiere consolidación periódica para mantener calidad. Confirmado 2026-04-10: las entradas automáticas de línea 88+ siguen siendo fragmentos sin valor accionable."
    confidence: 0.6
    scope: project
    source: "APRENDIZAJES.md"
    evidence_count: 1
    last_validated: "2026-04-06"
    contradictions: 0
    status: active
    tags: ["gotcha"]
    created_at: "2026-04-19"
    seccion_origen: "Gotchas del sistema"

  - id: inst-022
    pattern: "Versión debe actualizarse en 15+ archivos — integrar checklist en `/swl:release` [CONFIRMADO x3]"
    description: "package.json, package-lock.json (2 ubicaciones), plugin.json, CLAUDE.md, INVENTARIO.md, HEALTH.md (3 ubicaciones), README.md, SETUP.md, AGENTS.md, COMMANDS.md, CHANGELOG.md, COMPACT.md, STATE.md. Confirmado el 2026-04-12 durante bump v5.4.10→v5.4.11: la lista completa son 15+ ubicaciones en 14 archivos distintos."
    confidence: 0.6
    scope: project
    source: "APRENDIZAJES.md"
    evidence_count: 1
    last_validated: "2026-04-06"
    contradictions: 0
    status: active
    tags: ["gotcha"]
    created_at: "2026-04-19"
    seccion_origen: "Gotchas del sistema"

  - id: inst-023
    pattern: "Skills fantasma en `skillsInvocables` rompen el grafo de dependencias"
    description: "Nunca referenciar nombres de skills inexistentes ni nombres de agentes en `skillsInvocables`. Ejemplo: `pagos-swl` referenciaba `\"seguridad\"` (skill inexistente, el real es `\"checklist-seguridad\"`) y `\"backend-node-swl\"` (nombre de agente, no de skill). Verificar existencia con `ls habilidades/ | grep nombre` antes de agregar."
    confidence: 0.6
    scope: project
    source: "APRENDIZAJES.md"
    evidence_count: 1
    last_validated: "2026-04-12"
    contradictions: 0
    status: active
    tags: ["gotcha"]
    created_at: "2026-04-19"
    seccion_origen: "Gotchas del sistema"

  - id: inst-024
    pattern: "Truncación de reportes de diagnóstico oculta problemas reales"
    description: "El `graph-builder.py` truncaba la lista de nodos huérfanos a 20, ocultando 81 de 101 problemas. Los reportes de diagnóstico NUNCA deben truncarse — mostrar el cuadro completo para tomar decisiones informadas."
    confidence: 0.6
    scope: project
    source: "APRENDIZAJES.md"
    evidence_count: 1
    last_validated: "2026-04-12"
    contradictions: 0
    status: active
    tags: ["gotcha"]
    created_at: "2026-04-19"
    seccion_origen: "Gotchas del sistema"

  - id: inst-025
    pattern: "`skillsInvocables: todos` debe expandirse a aristas reales en el grafo"
    description: "Los agentes con `skillsInvocables: todos` (planificador-swl, investigador-swl) no generaban aristas en el grafo. Sin expansión, su grado era 2 cuando el real es 126. El graph-builder.py ahora expande `todos` al set completo de skill_ids."
    confidence: 0.6
    scope: project
    source: "APRENDIZAJES.md"
    evidence_count: 1
    last_validated: "2026-04-12"
    contradictions: 0
    status: active
    tags: ["gotcha"]
    created_at: "2026-04-19"
    seccion_origen: "Gotchas del sistema"

  - id: inst-026
    pattern: "Formato mixto YAML-lista + CSV en `skillsInvocables` causa parsing roto"
    description: "`frontend-react-swl` y `disenador-ui-swl` tenían líneas `- item` debajo de una línea CSV en `skillsInvocables`. El parser YAML interpreta esto como estructura inválida. El formato DEBE ser CSV puro en una sola línea. `disenador-ui-swl` queda pendiente de corrección."
    confidence: 0.6
    scope: project
    source: "APRENDIZAJES.md"
    evidence_count: 1
    last_validated: "2026-04-12"
    contradictions: 0
    status: active
    tags: ["gotcha"]
    created_at: "2026-04-19"
    seccion_origen: "Gotchas del sistema"