# 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).
