@saulwade/swl-ses 2.3.0 → 2.4.1

package/reglas/consultar-vault-primero.md

@@ -1,195 +1,195 @@
-# Regla: Consultar el vault Obsidian antes de leer múltiples archivos
-
-Esta regla es OBLIGATORIA y aplica cuando Claude necesita contexto de dominio
-(arquitectura, decisiones, patrones, lecciones, vocabulario del proyecto) antes
-de implementar, debugear, planificar o responder preguntas no triviales.
-
-El vault Obsidian del usuario es **fuente de verdad curada**: contiene resúmenes,
-ADRs, notas de decisiones, índices de proyectos, lecciones aprendidas. Está
-indexado y consultable vía MCP server `obsidian`. Leer ahí primero es más
-eficiente en tokens que leer múltiples archivos del codebase.
-
----
-
-## Principio
-
-> Antes de leer **3 o más archivos completos** del codebase para construir
-> contexto general (arquitectura, decisiones previas, convenciones del proyecto,
-> patrones), **consulta el vault Obsidian primero** con `obsidian_simple_search`
-> o `obsidian_complex_search`. Lee únicamente las notas relevantes. Solo cae
-> al codebase para los detalles concretos que el vault no cubra.
-
-Esto reduce el contexto consumido y aprovecha el conocimiento que el usuario ya
-sintetizó manualmente.
-
----
-
-## Cuándo aplicar
-
-OBLIGATORIO consultar el vault antes de:
-
-- Empezar una sesión nueva en un proyecto donde el usuario menciona terminología
-  específica (nombres de sistemas, ADRs, conceptos del dominio)
-- **Tomar una decisión de diseño, arquitectura o scope** — en CUALQUIER
-  proyecto, no solo en uno desconocido. El usuario tiene decisiones ya tomadas
-  que se repiten y no quiere reabrirlas
-- Buscar el "por qué" detrás de una elección arquitectónica
-- Resolver un bug donde la causa puede estar documentada en lecciones aprendidas
-- Investigar si un patrón ya fue evaluado y descartado
-- Responder "¿qué dice tu sistema sobre X?" o "¿cómo manejamos Y?"
-- **Antes de proponer una solución que parece "obvia"** — si suena obvia, alta
-  probabilidad de que el usuario ya pasó por ahí y haya una decisión documentada
-
-NO aplicar cuando:
-
-- La tarea es claramente local a 1-2 archivos del codebase (fix puntual, rename)
-- El usuario pidió explícitamente leer un archivo específico
-- Es una operación de comando puro (git, npm install, builds)
-- El proyecto no es del usuario (repos de terceros, código de exploración)
-
----
-
-## Tipos de conocimiento valioso que el vault repite
-
-El vault no es archivo histórico — es **memoria operacional activa**. Los
-siguientes tipos de contenido se repiten a través de proyectos y sesiones:
-
-| Tipo | Por qué consultarlo | Ejemplo de query |
-|---|---|---|
-| **ADRs vigentes y propuestos** | Decisiones de arquitectura que el usuario YA tomó y no quiere debatir otra vez | `obsidian_simple_search` con nombre del componente o tecnología |
-| **Patrones validados** | Soluciones que el usuario aprobó en sesiones previas para problemas equivalentes | búsqueda por keyword del problema |
-| **Anti-patrones documentados** | Caminos que el usuario YA rechazó — proponerlos otra vez es regresión | búsqueda por síntoma del bug o patrón |
-| **Vocabulario y convenciones del dominio** | Términos específicos del proyecto (OIC, VBO, papel de trabajo) que tienen significado preciso | nombre del término |
-| **Lecciones de incidentes** | Bugs ya investigados con causa raíz documentada | búsqueda por mensaje de error o síntoma |
-| **Diferencias entre proyectos del usuario** | SIGAF vs SIGM vs swl-ses tienen convenciones distintas — el vault las separa | path filtering por carpeta del proyecto |
-| **Roadmap y prioridades** | Lo que el usuario quiere para próximos sprints vs lo que está cerrado | búsqueda por nombre de feature |
-
-**Regla práctica**: si la decisión que vas a tomar es del tipo "el usuario
-probablemente ya pensó en esto", consulta antes. La probabilidad de que
-exista nota relevante en el vault es alta.
-
----
-
-## Cómo consultar
-
-### Tools disponibles del MCP `obsidian`
-
-| Tool | Cuándo usar |
-|---|---|
-| `obsidian_simple_search` | Búsqueda full-text por keywords. Primer paso siempre. |
-| `obsidian_complex_search` | Filtros estructurados (frontmatter, tags, paths). Cuando simple_search devuelve demasiado. |
-| `obsidian_list_files_in_vault` | Inventario completo del vault. Solo en sesión inicial de un proyecto. |
-| `obsidian_list_files_in_dir` | Listar notas de una carpeta específica. |
-| `obsidian_get_file_contents` | Leer una nota completa identificada por path relativo al vault. |
-| `obsidian_recent_changes` | Notas modificadas recientemente. Útil para retomar trabajo reciente. |
-| `obsidian_periodic_notes` | Daily/weekly notes si el usuario las usa. |
-
-### Workflow estándar
-
-1. **Search**: `obsidian_simple_search` con 2-4 keywords del dominio del problema.
-2. **Triage**: revisar paths de las notas devueltas. Identificar las 1-3 más
-   relevantes por nombre de archivo y context score.
-3. **Read targeted**: `obsidian_get_file_contents` solo de esas 1-3 notas.
-4. **Fallback al codebase**: si el vault no tiene info suficiente, ahí sí leer
-   archivos del codebase — pero con foco específico, no exploración amplia.
-
-### Anti-patrones
-
-- ❌ Leer 5+ archivos del codebase para entender la arquitectura sin haber
-  consultado el vault primero.
-- ❌ Llamar `obsidian_list_files_in_vault` y leer todo — el vault puede tener
-  cientos de notas. Usar search siempre antes que list.
-- ❌ Ignorar el vault porque "el codebase es fuente de verdad" — el codebase
-  es la fuente de verdad del CÓDIGO; el vault es la fuente de verdad de las
-  DECISIONES y el CONTEXTO.
-- ❌ Re-leer la misma nota del vault en turnos sucesivos del mismo proyecto —
-  el contenido ya está en contexto, citarlo directamente.
-- ❌ **Re-abrir una decisión ya documentada en el vault** porque "no la
-  recuerdo en este turno". Si la decisión está en una nota del usuario,
-  consultarla en lugar de re-debatir el tradeoff desde cero. El usuario
-  ya pagó el costo de decidir — no obligarlo a re-pagar.
-- ❌ **Proponer una solución sin verificar si el vault tiene una nota
-  contraria**. Si el usuario propuso X hace 2 meses y lo rechazó por razón
-  Y documentada en el vault, proponer X otra vez es regresión silenciosa.
-- ❌ **Asumir que "es un proyecto nuevo, no hay nada en el vault"** sin
-  buscar. El vault tiene notas transversales (decisiones arquitectónicas
-  del usuario, convenciones de naming, stack preferido) que aplican
-  cross-proyecto.
-- ❌ **Defaultear a Bash+filesystem cuando los tools `mcp__obsidian__*`
-  aparecen como deferred ("schemas not loaded")**. Tools deferred ≠ tools
-  ausentes — el MCP server está corriendo, solo falta cargar schemas vía
-  `ToolSearch(query="select:mcp__obsidian__obsidian_simple_search", ...)`.
-  Si Bash+cp+heredoc parece "más fácil", es inercia del workaround antiguo.
-  La ruta MCP es **siempre superior** para escritura al vault: patches
-  dirigidos por sección con `obsidian_patch_content` (target_type heading),
-  sin staging intermedio, sin tocar `proteccion-rutas.js`, auditable
-  nativamente por el plugin Local REST API.
-- ❌ **Tras un bloqueo de hook hacia el vault, recurrir al workaround
-  conocido sin reconsiderar el canal nuevo**. El MCP `obsidian` opera vía
-  HTTPS al puerto 27124 — NO pasa por el hook `proteccion-rutas.js`
-  (es protocolo MCP, no operación de filesystem). Cuando un destino esté
-  fuera del CWD, evaluar primero `mcp__obsidian__*` antes de defaultear
-  a Bash + cp.
-
-### Workflow forzoso para escritura al vault
-
-Si la operación es **escribir** al vault (no solo leer):
-
-1. Verificar si los tools `mcp__obsidian__obsidian_patch_content` y
-   `mcp__obsidian__obsidian_append_content` están cargados.
-2. Si aparecen como deferred → invocar `ToolSearch` con
-   `select:<tool-name>` para cargar el schema.
-3. Solo si el MCP no responde tras 5s o no está registrado → caer al
-   filesystem como fallback con disclaimer al usuario ("MCP no disponible,
-   uso filesystem y staging").
-4. NUNCA escribir al vault vía Bash + heredoc + cp como primera opción
-   cuando el MCP está disponible. Es deuda operativa con costo en cada
-   sesión futura.
-
----
-
-## Vault del usuario
-
-- **Path**: `F:\Google Drive\Developer\Obsidian\Vault\SWL` (sincronizado vía
-  Google Drive entre WISC y WISCLAP)
-- **Contenido típico**: notas sobre el sistema SWL, decisiones de arquitectura,
-  ADRs, lecciones de sesiones pasadas, vocabulario específico del dominio
-- **Plugin habilitador**: Local REST API en Obsidian (puerto 27124, HTTPS)
-- **Precondición**: Obsidian debe estar corriendo en la máquina actual para
-  que el MCP responda. Si no responde, fallback al codebase con disclaimer
-  al usuario ("Obsidian no está corriendo, no pude consultar el vault").
-
----
-
-## Excepciones documentadas
-
-- Si `obsidian_simple_search` devuelve 0 resultados para keywords razonables
-  del dominio, el vault no cubre el tema — proceder con codebase sin más
-  intentos en el vault.
-- Si Obsidian no está corriendo (timeout o connection refused), reportarlo
-  al usuario en una línea breve y proceder con codebase. NO bloquear el flujo.
-- Para tareas donde el usuario explícitamente dice "no consultes nada, solo
-  haz X", respetar — esto es preferencia explícita.
-
----
-
-## Aplicabilidad
-
-Esta regla aplica a:
-- Claude Code (CLI y Desktop)
-- Cualquier agente del sistema SWL que necesite contexto de dominio
-- Sesiones de planning, debugging, arquitectura, code review
-
-NO aplica a:
-- Sub-agentes que solo hacen una tarea atómica (formateo, lint, build)
-- Agentes que operan exclusivamente sobre archivos pasados como argumento
-
----
-
-## Origen
-
-Formalizada el 2026-05-09 al instalar el MCP server `mcp-obsidian` (Python,
-MarkusPfundstein) en WISCLAP para evitar el patrón observado de leer múltiples
-archivos del codebase para reconstruir contexto que ya estaba sintetizado en
-el vault. La regla aplica cross-machine vía Syncthing (`~/.claude/rules/` se
-sincroniza automáticamente).
+# Regla: Consultar el vault Obsidian antes de leer múltiples archivos
+
+Esta regla es OBLIGATORIA y aplica cuando Claude necesita contexto de dominio
+(arquitectura, decisiones, patrones, lecciones, vocabulario del proyecto) antes
+de implementar, debugear, planificar o responder preguntas no triviales.
+
+El vault Obsidian del usuario es **fuente de verdad curada**: contiene resúmenes,
+ADRs, notas de decisiones, índices de proyectos, lecciones aprendidas. Está
+indexado y consultable vía MCP server `obsidian`. Leer ahí primero es más
+eficiente en tokens que leer múltiples archivos del codebase.
+
+---
+
+## Principio
+
+> Antes de leer **3 o más archivos completos** del codebase para construir
+> contexto general (arquitectura, decisiones previas, convenciones del proyecto,
+> patrones), **consulta el vault Obsidian primero** con `obsidian_simple_search`
+> o `obsidian_complex_search`. Lee únicamente las notas relevantes. Solo cae
+> al codebase para los detalles concretos que el vault no cubra.
+
+Esto reduce el contexto consumido y aprovecha el conocimiento que el usuario ya
+sintetizó manualmente.
+
+---
+
+## Cuándo aplicar
+
+OBLIGATORIO consultar el vault antes de:
+
+- Empezar una sesión nueva en un proyecto donde el usuario menciona terminología
+  específica (nombres de sistemas, ADRs, conceptos del dominio)
+- **Tomar una decisión de diseño, arquitectura o scope** — en CUALQUIER
+  proyecto, no solo en uno desconocido. El usuario tiene decisiones ya tomadas
+  que se repiten y no quiere reabrirlas
+- Buscar el "por qué" detrás de una elección arquitectónica
+- Resolver un bug donde la causa puede estar documentada en lecciones aprendidas
+- Investigar si un patrón ya fue evaluado y descartado
+- Responder "¿qué dice tu sistema sobre X?" o "¿cómo manejamos Y?"
+- **Antes de proponer una solución que parece "obvia"** — si suena obvia, alta
+  probabilidad de que el usuario ya pasó por ahí y haya una decisión documentada
+
+NO aplicar cuando:
+
+- La tarea es claramente local a 1-2 archivos del codebase (fix puntual, rename)
+- El usuario pidió explícitamente leer un archivo específico
+- Es una operación de comando puro (git, npm install, builds)
+- El proyecto no es del usuario (repos de terceros, código de exploración)
+
+---
+
+## Tipos de conocimiento valioso que el vault repite
+
+El vault no es archivo histórico — es **memoria operacional activa**. Los
+siguientes tipos de contenido se repiten a través de proyectos y sesiones:
+
+| Tipo | Por qué consultarlo | Ejemplo de query |
+|---|---|---|
+| **ADRs vigentes y propuestos** | Decisiones de arquitectura que el usuario YA tomó y no quiere debatir otra vez | `obsidian_simple_search` con nombre del componente o tecnología |
+| **Patrones validados** | Soluciones que el usuario aprobó en sesiones previas para problemas equivalentes | búsqueda por keyword del problema |
+| **Anti-patrones documentados** | Caminos que el usuario YA rechazó — proponerlos otra vez es regresión | búsqueda por síntoma del bug o patrón |
+| **Vocabulario y convenciones del dominio** | Términos específicos del proyecto (OIC, VBO, papel de trabajo) que tienen significado preciso | nombre del término |
+| **Lecciones de incidentes** | Bugs ya investigados con causa raíz documentada | búsqueda por mensaje de error o síntoma |
+| **Diferencias entre proyectos del usuario** | SIGAF vs SIGM vs swl-ses tienen convenciones distintas — el vault las separa | path filtering por carpeta del proyecto |
+| **Roadmap y prioridades** | Lo que el usuario quiere para próximos sprints vs lo que está cerrado | búsqueda por nombre de feature |
+
+**Regla práctica**: si la decisión que vas a tomar es del tipo "el usuario
+probablemente ya pensó en esto", consulta antes. La probabilidad de que
+exista nota relevante en el vault es alta.
+
+---
+
+## Cómo consultar
+
+### Tools disponibles del MCP `obsidian`
+
+| Tool | Cuándo usar |
+|---|---|
+| `obsidian_simple_search` | Búsqueda full-text por keywords. Primer paso siempre. |
+| `obsidian_complex_search` | Filtros estructurados (frontmatter, tags, paths). Cuando simple_search devuelve demasiado. |
+| `obsidian_list_files_in_vault` | Inventario completo del vault. Solo en sesión inicial de un proyecto. |
+| `obsidian_list_files_in_dir` | Listar notas de una carpeta específica. |
+| `obsidian_get_file_contents` | Leer una nota completa identificada por path relativo al vault. |
+| `obsidian_recent_changes` | Notas modificadas recientemente. Útil para retomar trabajo reciente. |
+| `obsidian_periodic_notes` | Daily/weekly notes si el usuario las usa. |
+
+### Workflow estándar
+
+1. **Search**: `obsidian_simple_search` con 2-4 keywords del dominio del problema.
+2. **Triage**: revisar paths de las notas devueltas. Identificar las 1-3 más
+   relevantes por nombre de archivo y context score.
+3. **Read targeted**: `obsidian_get_file_contents` solo de esas 1-3 notas.
+4. **Fallback al codebase**: si el vault no tiene info suficiente, ahí sí leer
+   archivos del codebase — pero con foco específico, no exploración amplia.
+
+### Anti-patrones
+
+- ❌ Leer 5+ archivos del codebase para entender la arquitectura sin haber
+  consultado el vault primero.
+- ❌ Llamar `obsidian_list_files_in_vault` y leer todo — el vault puede tener
+  cientos de notas. Usar search siempre antes que list.
+- ❌ Ignorar el vault porque "el codebase es fuente de verdad" — el codebase
+  es la fuente de verdad del CÓDIGO; el vault es la fuente de verdad de las
+  DECISIONES y el CONTEXTO.
+- ❌ Re-leer la misma nota del vault en turnos sucesivos del mismo proyecto —
+  el contenido ya está en contexto, citarlo directamente.
+- ❌ **Re-abrir una decisión ya documentada en el vault** porque "no la
+  recuerdo en este turno". Si la decisión está en una nota del usuario,
+  consultarla en lugar de re-debatir el tradeoff desde cero. El usuario
+  ya pagó el costo de decidir — no obligarlo a re-pagar.
+- ❌ **Proponer una solución sin verificar si el vault tiene una nota
+  contraria**. Si el usuario propuso X hace 2 meses y lo rechazó por razón
+  Y documentada en el vault, proponer X otra vez es regresión silenciosa.
+- ❌ **Asumir que "es un proyecto nuevo, no hay nada en el vault"** sin
+  buscar. El vault tiene notas transversales (decisiones arquitectónicas
+  del usuario, convenciones de naming, stack preferido) que aplican
+  cross-proyecto.
+- ❌ **Defaultear a Bash+filesystem cuando los tools `mcp__obsidian__*`
+  aparecen como deferred ("schemas not loaded")**. Tools deferred ≠ tools
+  ausentes — el MCP server está corriendo, solo falta cargar schemas vía
+  `ToolSearch(query="select:mcp__obsidian__obsidian_simple_search", ...)`.
+  Si Bash+cp+heredoc parece "más fácil", es inercia del workaround antiguo.
+  La ruta MCP es **siempre superior** para escritura al vault: patches
+  dirigidos por sección con `obsidian_patch_content` (target_type heading),
+  sin staging intermedio, sin tocar `proteccion-rutas.js`, auditable
+  nativamente por el plugin Local REST API.
+- ❌ **Tras un bloqueo de hook hacia el vault, recurrir al workaround
+  conocido sin reconsiderar el canal nuevo**. El MCP `obsidian` opera vía
+  HTTPS al puerto 27124 — NO pasa por el hook `proteccion-rutas.js`
+  (es protocolo MCP, no operación de filesystem). Cuando un destino esté
+  fuera del CWD, evaluar primero `mcp__obsidian__*` antes de defaultear
+  a Bash + cp.
+
+### Workflow forzoso para escritura al vault
+
+Si la operación es **escribir** al vault (no solo leer):
+
+1. Verificar si los tools `mcp__obsidian__obsidian_patch_content` y
+   `mcp__obsidian__obsidian_append_content` están cargados.
+2. Si aparecen como deferred → invocar `ToolSearch` con
+   `select:<tool-name>` para cargar el schema.
+3. Solo si el MCP no responde tras 5s o no está registrado → caer al
+   filesystem como fallback con disclaimer al usuario ("MCP no disponible,
+   uso filesystem y staging").
+4. NUNCA escribir al vault vía Bash + heredoc + cp como primera opción
+   cuando el MCP está disponible. Es deuda operativa con costo en cada
+   sesión futura.
+
+---
+
+## Vault del usuario
+
+- **Path**: `F:\Google Drive\Developer\Obsidian\Vault\SWL` (sincronizado vía
+  Google Drive entre WISC y WISCLAP)
+- **Contenido típico**: notas sobre el sistema SWL, decisiones de arquitectura,
+  ADRs, lecciones de sesiones pasadas, vocabulario específico del dominio
+- **Plugin habilitador**: Local REST API en Obsidian (puerto 27124, HTTPS)
+- **Precondición**: Obsidian debe estar corriendo en la máquina actual para
+  que el MCP responda. Si no responde, fallback al codebase con disclaimer
+  al usuario ("Obsidian no está corriendo, no pude consultar el vault").
+
+---
+
+## Excepciones documentadas
+
+- Si `obsidian_simple_search` devuelve 0 resultados para keywords razonables
+  del dominio, el vault no cubre el tema — proceder con codebase sin más
+  intentos en el vault.
+- Si Obsidian no está corriendo (timeout o connection refused), reportarlo
+  al usuario en una línea breve y proceder con codebase. NO bloquear el flujo.
+- Para tareas donde el usuario explícitamente dice "no consultes nada, solo
+  haz X", respetar — esto es preferencia explícita.
+
+---
+
+## Aplicabilidad
+
+Esta regla aplica a:
+- Claude Code (CLI y Desktop)
+- Cualquier agente del sistema SWL que necesite contexto de dominio
+- Sesiones de planning, debugging, arquitectura, code review
+
+NO aplica a:
+- Sub-agentes que solo hacen una tarea atómica (formateo, lint, build)
+- Agentes que operan exclusivamente sobre archivos pasados como argumento
+
+---
+
+## Origen
+
+Formalizada el 2026-05-09 al instalar el MCP server `mcp-obsidian` (Python,
+MarkusPfundstein) en WISCLAP para evitar el patrón observado de leer múltiples
+archivos del codebase para reconstruir contexto que ya estaba sintetizado en
+el vault. La regla aplica cross-machine vía Syncthing (`~/.claude/rules/` se
+sincroniza automáticamente).