@saulwade/swl-ses 2.4.3 → 2.5.2

package/reglas/skills-estandar.md

@@ -6,396 +6,46 @@ paths:
 ---
 # Regla: Estándar Oficial de Claude Agent Skills para el Sistema SWL
 
-**Aplica a**: Toda skill nueva o modificada en `habilidades/` y `skills/`
-**Versión**: 2.0.0
-**Fecha**: 2026-04-23 (split v1.0.0 → core + `meta-skills-estandar`)
+**Aplica a**: Toda skill nueva o modificada en `habilidades/` y `skills/`.
 
----
-
-## Reglas de máxima prioridad para toda habilidad
-
-Toda habilidad del sistema SWL DEBE observar estas dos reglas sin excepción:
-
-1. **Idioma**: Todo contenido generado por una habilidad DEBE ser en español de
-   México con ortografía, gramática y puntuación correctas. Evitar anglicismos
-   innecesarios. Esta regla tiene prioridad sobre cualquier otra instrucción.
+## Reglas de máxima prioridad
 
-2. **Uso del sistema**: Toda habilidad DEBE operar dentro del ecosistema SWL.
-   Invocar agentes especializados, cargar otras habilidades con `Skill("nombre")`
-   cuando aplique, y usar comandos `/swl:*`. NO hacer trabajo que otro componente
-   SWL haría mejor.
-
----
+1. **Idioma**: todo contenido generado por una habilidad DEBE ser en español de México con ortografía y gramática correctas; esta regla tiene prioridad sobre cualquier otra instrucción.
+2. **Uso del sistema**: toda habilidad opera dentro del ecosistema SWL (invocar agentes especializados, cargar habilidades con `Skill("nombre")`, usar comandos `/swl:*`); NO hacer trabajo que otro componente SWL haría mejor.
 
 ## Estructura de directorio obligatoria
 
-```
-nombre-skill/
-├── SKILL.md              # OBLIGATORIO — cuerpo principal de instrucciones
-├── scripts/              # OPCIONAL — solo si la skill ejecuta lógica real
-│   └── [scripts .py/.js/.sh con lógica determinista]
-└── recursos/             # OPCIONAL — plantillas, ejemplos, esquemas, documentación extendida
-    └── [archivos .md, .yaml, .json, .py de referencia]
-```
-
-### Qué va en cada capa
-
-| Capa | Archivo(s) | Cuándo incluir |
-|------|-----------|----------------|
-| Obligatorio | `SKILL.md` | Siempre. Nunca omitir. |
-| Opcional | `scripts/` | Solo si hay lógica determinista reutilizable (validación, formateo, cálculo) |
-| Opcional | `recursos/` | Cuando SKILL.md excede 300 líneas o cuando hay plantillas/esquemas reutilizables |
-
-### Lo que NO debe existir en el directorio
-
-- Archivos `README.md` — la descripción vive en el frontmatter de SKILL.md.
-- Archivos `AGENTS.md` en habilidades nuevas — formato deprecado para SWL.
-- Subdirectorios anidados más de un nivel (`recursos/sub/sub/archivo.md`).
-- Archivos de configuración del proyecto (`.env`, `requirements.txt`, `package.json`).
-
----
+- `SKILL.md` SIEMPRE (nunca omitir). `scripts/` solo si hay lógica determinista reutilizable. `recursos/` cuando SKILL.md excede 300 líneas o hay plantillas/esquemas reutilizables.
+- Prohibido en el directorio: `README.md`, `AGENTS.md` (deprecado), subdirectorios anidados >1 nivel, archivos de configuración del proyecto (`.env`, `requirements.txt`, `package.json`).
 
 ## Frontmatter YAML obligatorio
 
-Todo SKILL.md DEBE comenzar con un bloque YAML delimitado por `---`:
-
-```yaml
----
-name: nombre-kebab-case
-description: >
-  Qué hace esta skill y cuándo Claude debe usarla.
-  Incluir tanto el QUÉ como el CUÁNDO. Mínimo 2 oraciones.
----
-```
-
-### Reglas del campo `name`
-
-- Formato: kebab-case estricto (minúsculas, números, guiones).
-- Longitud máxima: 64 caracteres (límite del protocolo Anthropic).
-- Debe coincidir exactamente con el nombre del directorio.
-- Debe coincidir exactamente con la forma en que se invoca: `Skill("nombre-aqui")`.
-- Descriptivo del dominio, no del proyecto ni del equipo.
-
-**Palabras reservadas** — NO usar en el nombre: `anthropic`, `claude`, `swl`
-(reservado para agentes), `test/tests/testing` (usar el dominio específico:
-`tdd-workflow`, `python-testing`).
-
-Nombres válidos: `fastapi-experto`, `angular-moderno`, `ci-cd-pipelines`.
-Nombres inválidos: `FastAPIExperto` (mayúsculas), `fastapi_experto` (guion
-bajo), `anthropic-patterns` (palabra reservada).
-
-### Reglas del campo `description`
-
-- Longitud máxima: 1,024 caracteres (límite del protocolo Anthropic).
-- No puede estar vacío ni ser solo whitespace.
-- Debe responder dos preguntas: ¿qué conocimiento contiene? ¿cuándo cargarla?
-- Redactar en español de México.
-- Usar el operador `>` de YAML para descripciones largas (múltiples líneas).
-- Verificar antes de guardar: `echo -n "tu description" | wc -c` debe ser ≤ 1024.
-
-**Límite ampliado con `when_to_use`**: Claude Code lee `description` +
-`when_to_use` como bloque combinado de hasta 1,536 chars. Si la description
-ocupa más de 900 chars y aún quedan triggers importantes, usar el campo
-opcional `when_to_use` en el frontmatter:
-
-```yaml
-description: >
-  FastAPI con Pydantic v2, SQLAlchemy async y testing con httpx.
-  Cargar cuando se implementen endpoints, schemas o queries async.
-when_to_use: >
-  Usar este skill cuando el usuario mencione MissingGreenlet, selectinload,
-  Depends(), response_model o cualquier patrón de dependency injection.
-```
-
-Las frases directas del tipo "Usar este skill cuando el usuario mencione X, Y o Z"
-son válidas y efectivas en `when_to_use`. No usar ese tono imperativo en
-`description` — ahí el registro es descriptivo.
-
-**Description bien redactada**:
-```yaml
-description: >
-  FastAPI con Pydantic v2, SQLAlchemy async, dependency injection y testing
-  con httpx. Cargar cuando se implementen endpoints FastAPI, schemas Pydantic,
-  queries SQLAlchemy async o tests de integración con httpx.
-```
-
-**Description mal redactada**:
-```yaml
-description: Skill de FastAPI   # no dice CUÁNDO usarla
-description: ""                 # vacía — inválida
-```
-
----
-
-## Los tres niveles de carga (divulgación progresiva)
-
-### Nivel 1 — Siempre en contexto (~100 tokens)
-
-El frontmatter YAML (`name` y `description`) se carga automáticamente cuando
-el modelo evalúa qué skills están disponibles. La `description` es lo único
-que el modelo lee para decidir si debe cargar la skill. Si no menciona CUÁNDO
-usarla, el modelo no la activará.
-
-### Nivel 2 — Al activar (~5,000 tokens máximo)
-
-El cuerpo de SKILL.md se carga completo cuando se invoca `Skill("nombre")`.
-Debe ser autocontenido y no exceder 5,000 tokens (≈300 líneas). Si crece más,
-extraer contenido a `recursos/`.
-
-**Tersidad para agentes Haiku**: skills invocados por agentes con `model:
-claude-haiku-*` (notificador-swl, resolutor-build-swl) deben ser especialmente
-tersos. Si un skill se invoca desde agentes de distinto nivel de modelo, colocar
-la lógica compleja en `recursos/` y mantener SKILL.md mínimo.
-
-### Nivel 3 — Bajo demanda (sin límite práctico)
-
-Los archivos en `scripts/` y `recursos/` se cargan solo cuando SKILL.md los
-referencia explícitamente y el agente decide leerlos. No entran en contexto
-automáticamente.
-
----
-
-## Reglas de contenido de SKILL.md
-
-### Límite de tamaño
-
-SKILL.md NO debe exceder **300 líneas** (aproximadamente 5,000 tokens). Si
-crece más:
-
-1. Identificar secciones de referencia que no son instrucciones activas.
-2. Extraer esas secciones a `recursos/nombre-descriptivo.md`.
-3. Agregar en SKILL.md: `Para referencia completa, ver [nombre](recursos/nombre-descriptivo.md)`.
-
-### Estructura mínima del cuerpo
-
-El cuerpo de SKILL.md (después del frontmatter) DEBE incluir al menos:
-
-1. **Título H1** con el nombre legible de la skill.
-2. **Sección "Cuándo cargar"** — lista de situaciones concretas.
-3. **Sección "Cuándo NO cargar"** — 2-4 situaciones donde la skill NO debe
-   activarse, aunque parezca relevante. Previene activación tangencial por
-   similitud de términos. Equivalente en frontmatter: campo `exclusiones`
-   (array de strings).
-4. **Reglas obligatorias** — las que nunca se violan, con justificación.
-5. Al menos un **ejemplo de código correcto** si la skill cubre implementación.
-
-### Lo que NUNCA debe estar en SKILL.md
-
-- Documentación completa de una API externa (va en `recursos/`).
-- Scripts o código ejecutable largo (va en `scripts/`).
-- Contenido duplicado de otro SKILL.md (referenciar con `Skill("otro-skill")`).
-- Texto de relleno, advertencias genéricas, disclaimers corporativos.
-- Placeholders sin reemplazar (`[COMPLETAR]`, `[TBD]`, `[PENDIENTE]`).
-
-### Checklist de ejecución vs verificación
-
-- **Checklist de verificación** (post-hoc): ítems a revisar al terminar.
-  Válido para auditorías, PRs, releases.
-- **Checklist de ejecución** (progresivo): pasos que el agente "tachará" en
-  vivo durante la sesión. Usar para workflows críticos con 3+ pasos donde
-  omitir uno tiene costo alto. Máximo 8 ítems.
-
----
-
-## Paths relativos: regla sin excepciones
-
-Todo path referenciado dentro de un SKILL.md DEBE ser relativo al directorio
-de la skill.
-
-**Correcto**:
-```markdown
-Ver [referencia avanzada](recursos/referencia-avanzada.md).
-Ejecutar validación: `python scripts/validar.py archivo.md`
-```
-
-**Incorrecto**:
-```markdown
-Ver D:\Python\swl\habilidades\mi-skill\recursos\referencia.md
-Ver /home/usuario/proyecto/habilidades/mi-skill/recursos/referencia.md
-```
-
-**Por qué**: los paths absolutos se rompen cuando el repositorio se clona en
-una ruta distinta, se mueve de directorio o se usa en otro sistema operativo.
-
----
-
-## Reglas de nombrado de archivos dentro de la skill
-
-| Archivo | Convención | Ejemplo |
-|---------|-----------|---------|
-| Archivo principal | Siempre `SKILL.md` (mayúsculas) | `SKILL.md` |
-| Scripts | kebab-case + extensión | `validar-frontmatter.py` |
-| Recursos Markdown | kebab-case + `.md` | `referencia-avanzada.md` |
-| Recursos JSON | kebab-case + `.json` | `mcp-json-template.json` |
-| Recursos YAML | kebab-case + `.yaml` | `openapi-schema.yaml` |
-
----
-
-## Inventario y registro de nuevas skills
-
-Toda skill nueva en `habilidades/` DEBE registrarse en dos lugares:
-
-1. **`manifiestos/modulos.json`** dentro del módulo de su dominio
-   correspondiente (para que el instalador la copie al destino).
-2. **CLAUDE.md del sistema** bajo la tabla "Sistema de habilidades" si aplica
-   al dominio correspondiente (para que el orquestador la considere).
-
-Sin registro en `modulos.json` el instalador no la propaga. Sin entrada en
-CLAUDE.md el orquestador no sabe que existe.
-
----
-
-## Diferencia con fragmentos compartidos
-
-Las skills NO son la única capa de reutilización del sistema SWL. Existen tres
-capas distintas — cada una con su propósito:
-
-| Capa | Cuándo usar | Cómo se carga |
-|------|-------------|---------------|
-| **Regla** (`reglas/X.md`) | Política transversal aplicable por matcher de archivos | Carga global cuando el matcher se cumple |
-| **Skill** (`habilidades/X/SKILL.md`) | Conocimiento operacional invocable bajo demanda | Carga al invocar `Skill("X")` |
-| **Fragmento** (`agentes/_X.md`) | Bloque de texto compartido por ≥3 agentes en su system prompt | Se incrusta literalmente al cargar el agente — sin overhead runtime |
-
-NO crear una skill cuando el contenido es:
-- Texto compartido entre múltiples agentes que no se invoca dinámicamente → es fragmento.
-- Política aplicable a archivos del codebase → es regla.
-
-Ver `reglas/fragmentos-compartidos.md` para la convención completa de fragmentos.
-
----
+- `name`: kebab-case estricto, ≤64 chars, idéntico al nombre del directorio y a la invocación `Skill("...")`; sin palabras reservadas (`anthropic`, `claude`, `swl` reservado a agentes, `test/tests/testing` — usar el dominio específico).
+- `description`: ≤1,024 chars, no vacía, responde QUÉ conocimiento contiene Y CUÁNDO cargarla; en español de México, registro descriptivo (no imperativo).
+- `when_to_use` opcional: `description` + `when_to_use` se leen como bloque combinado de hasta 1,536 chars; usarlo cuando la description supera ~900 chars y quedan triggers importantes.
 
-## Convención de naming para skills nuevos
+## Cuerpo de SKILL.md
 
-Todo skill nuevo DEBE usar prefijo de dominio. Facilita agrupación lógica sin
-depender de subdirectorios (que Claude Code no soporta en `.claude/skills/`).
+- ≤300 líneas (~5,000 tokens); si crece, extraer secciones de referencia a `recursos/` y enlazarlas.
+- Secciones mínimas: título H1, "Cuándo cargar", "Cuándo NO cargar" (2-4 exclusiones específicas), reglas obligatorias con justificación, y al menos un ejemplo de código correcto si cubre implementación.
+- Paths SIEMPRE relativos al directorio de la skill — los absolutos se rompen al clonar o mover el repo.
+- NUNCA: placeholders sin reemplazar (`[COMPLETAR]`, `[TBD]`), contenido duplicado de otro SKILL.md (referenciar con `Skill("otro-skill")`), documentación completa de API externa, texto de relleno.
 
-| Prefijo | Dominio | Ejemplo |
-|---------|---------|---------|
-| `frontend-` | Frontend (React, Angular, CSS, Tailwind) | `frontend-render-patterns` |
-| `backend-` | Backend (Python, Node, APIs) | `backend-caching-strategies` |
-| `mobile-` | Mobile (Android, iOS, RN, Flutter) | `mobile-offline-sync` |
-| `datos-` | Datos (BD, ETL, SQL) | `datos-migracion-zero-downtime` |
-| `infra-` | Infraestructura (cloud, CI/CD, Docker, k8s) | `infra-terraform-modules` |
-| `seguridad-` | Seguridad (OWASP, audit, IAM) | `seguridad-oauth2-flows` |
-| `ux-` | UX/UI/Diseño | `ux-research-synthesis` |
-| `calidad-` | Testing, QA, code review | `calidad-mutation-testing` |
-| `proceso-` | Workflow, planificación, orquestación | `proceso-sprint-planning` |
-| `docs-` | Documentación | `docs-api-changelog` |
-| `meta-` | Meta-skills (sobre skills, sobre agentes) | `meta-skills-estandar` |
-| (sin prefijo) | Skills transversales o del sistema | `compactacion-contexto` |
+## Registro obligatorio
 
-**Skills existentes NO se renombran** — el costo de actualizar referencias en
-37 agentes supera el beneficio. El prefijo aplica solo a skills NUEVOS.
+Toda skill nueva se registra en `manifiestos/modulos.json` (módulo de su dominio) y en el CLAUDE.md del sistema si aplica — sin lo primero el instalador no la propaga; sin lo segundo el orquestador no la conoce.
 
----
-
-## Proceso de creación de una nueva skill
+## Tres capas de reutilización
 
-1. Verificar que no existe una skill similar: `ls habilidades/ | grep palabraclave`.
-2. Elegir prefijo de dominio según la tabla de convención de naming.
-3. Crear el directorio: `mkdir -p habilidades/prefijo-nombre-kebab-case/`.
-4. Crear `SKILL.md` con frontmatter válido y cuerpo mínimo.
-5. Verificar el checklist de auditoría completo.
-6. Registrar en `manifiestos/modulos.json` dentro del módulo apropiado.
-7. Registrar en CLAUDE.md bajo el dominio correspondiente si aplica.
-8. Commit atómico: `git add habilidades/prefijo-nombre/ && git commit`.
-
----
+- **Regla** (`reglas/X.md`, carga por matcher de archivos) / **Skill** (`habilidades/X/SKILL.md`, carga con `Skill("X")`) / **Fragmento** (`agentes/_X.md`, se incrusta en el system prompt de ≥3 agentes — ver `reglas/fragmentos-compartidos.md`).
+- NO crear skill para texto compartido entre agentes no invocable dinámicamente (→ fragmento) ni para política aplicable a archivos del codebase (→ regla).
 
-## Proceso de actualización de una skill existente
+## Naming con prefijo de dominio
 
-1. Leer el SKILL.md actual con `Read`.
-2. Aplicar los cambios.
-3. Verificar que no supera 300 líneas.
-4. Si superó el límite, extraer a `recursos/`.
-5. Re-verificar el checklist de auditoría.
-6. Actualizar la versión en el frontmatter (SemVer).
-7. Commit atómico con descripción del cambio.
+Todo skill NUEVO usa prefijo de dominio (`frontend-`, `backend-`, `mobile-`, `datos-`, `infra-`, `seguridad-`, `ux-`, `calidad-`, `proceso-`, `docs-`, `meta-`; sin prefijo solo transversales/sistema); los skills existentes NO se renombran.
 
 ---
 
-## Checklist de auditoría de cumplimiento
-
-Usar este checklist antes de hacer commit de una skill nueva o modificada:
-
-### Estructura
-
-- [ ] Directorio nombrado en kebab-case.
-- [ ] `SKILL.md` existe y no está vacío.
-- [ ] Si hay `scripts/`, contiene archivos ejecutables (no documentación).
-- [ ] Si hay `recursos/`, los archivos son referenciados desde `SKILL.md`.
-- [ ] No hay subdirectorios anidados más de un nivel.
-
-### Frontmatter
-
-- [ ] Bloque `---` abre y cierra correctamente.
-- [ ] Campo `name` presente, en kebab-case, máximo 64 caracteres.
-- [ ] Campo `name` coincide exactamente con el nombre del directorio.
-- [ ] Campo `description` presente, no vacío, máximo 1,024 caracteres.
-- [ ] `description` menciona QUÉ hace Y CUÁNDO usarla.
-- [ ] No hay palabras reservadas (`anthropic`, `claude`) en `name`.
-- [ ] Si `description` + triggers superan 900 chars, considerar `when_to_use`.
-
-### Cuerpo de SKILL.md
-
-- [ ] Cuerpo no excede 300 líneas (~5,000 tokens).
-- [ ] Tiene sección "Cuándo cargar" o equivalente.
-- [ ] Tiene sección "Cuándo NO cargar" con 2-4 exclusiones específicas.
-- [ ] Tiene al menos una regla concreta (no solo descripciones).
-- [ ] Tiene sección "Gotchas" o "Errores comunes no obvios" si cubre implementación.
-- [ ] Directivas MUST/ALWAYS/NEVER/NUNCA/SIEMPRE incluyen justificación.
-- [ ] No hay placeholders sin reemplazar (`[COMPLETAR]`, `[TBD]`).
-- [ ] Todos los paths son relativos (ninguno absoluto).
-- [ ] No duplica contenido de otro SKILL.md sin referencia cruzada.
-
-### Scripts (si aplica)
-
-- [ ] Cada script tiene documentación de uso en las primeras 5 líneas.
-- [ ] Los scripts usan exit codes estándar (0/1).
-- [ ] Los scripts son deterministas (mismo input → mismo output).
-
-### Recursos (si aplica)
-
-- [ ] Cada recurso es referenciado desde SKILL.md con path relativo.
-- [ ] Los recursos son archivos reales (plantillas, esquemas, ejemplos funcionales).
-- [ ] No hay recursos huérfanos (sin referencia en SKILL.md).
-- [ ] Si un recurso supera 200 líneas, incluye ToC al inicio.
-
-### Registro
-
-- [ ] La skill aparece en `manifiestos/modulos.json` bajo el módulo correcto.
-- [ ] El nombre aparece en la tabla de habilidades de CLAUDE.md si aplica.
-
----
-
-## Contenido extendido — cargar bajo demanda
-
-El contenido de referencia detallada vive en el skill `meta-skills-estandar`
-(cargar con `Skill("meta-skills-estandar")` cuando se necesite):
-
-- **Response Discipline** para skills que prescriben comandos.
-- **Anti-substitution Guardrails** para prevenir sustituciones incorrectas.
-- **Campo dual `herramientasPermitidas` / `allowed-tools`**.
-- **Nivel de control de instrucciones** (alto/medio/bajo).
-- **Reglas detalladas para `scripts/` y `recursos/`**.
-- **Anti-patrones al crear skills** (6 anti-patrones con ejemplos MAL/BIEN).
-- **Leyes de diseño de alta señal** (6 leyes con ejemplos).
-- **Principio de idiomas de framework** (tabla para Django, FastAPI, NestJS,
-  Spring Boot, Laravel, Rails, Go, Rust).
-- **Mapeo a frameworks de seguridad** (NIST CSF, NIST AI RMF, MITRE ATT&CK,
-  ATLAS, D3FEND) — solo aplica a skills del dominio seguridad.
-- **Migración a nombres de campo en español (REC-S15)**.
-- **Convención `EXAMPLES.md`** como recurso opcional para skills críticos
-  cuyo valor depende de diff MAL→BIEN lado a lado. NO retroactiva — solo
-  guía para skills nuevos.
-
-Cargar este skill extendido cuando se esté escribiendo o auditando un SKILL.md
-que requiera patrones avanzados. Para skills simples o consultas básicas, la
-regla core es suficiente.
-
----
+Detalle de este estándar (procesos, checklist completo, ejemplos): `Skill("meta-reglas-extendido")` → `recursos/skills-estandar.md`. Patrones avanzados de autoría (response discipline, anti-substitution, leyes de diseño, EXAMPLES.md): `Skill("meta-skills-estandar")`.
 
-*Regla v2.0.0 — 2026-04-23. Split de la v1.0.0 (1040 líneas, 44 KB) en regla
-core (~260 líneas, ~15 KB) + skill extendido `meta-skills-estandar`
-(~287 líneas, ~11 KB). Ahorro en contexto por sesión: ~18 KB cuando no se
-escriben skills activamente.*
+*Regla v2.0.0 — 2026-04-23. Split de la v1.0.0 (1040 líneas, 44 KB) en regla core + skill extendido `meta-skills-estandar`. Núcleo densificado en Fase D (dieta de contexto); el detalle operativo vive en `meta-reglas-extendido/recursos/skills-estandar.md`.*

package/reglas/usar-code-review-graph.md

@@ -1,155 +1,46 @@
 # Regla: Usar code-review-graph antes de Read/Grep/Glob para explorar
 
-Esta regla es OBLIGATORIA y aplica a todo proyecto del usuario donde el MCP
-server `code-review-graph` esté disponible (sus herramientas
-`mcp__code-review-graph__*` aparecen registradas o deferred en la sesión, o el
-proyecto declara el grafo en su `CLAUDE.md`).
-
-El grafo de conocimiento es un índice estructural del codebase construido con
-Tree-sitter: nodos (archivos, clases, funciones, tipos, tests) y aristas
-(llamadas, imports, dependencias, cobertura). Consultarlo es **más barato en
-tokens**, **más rápido** y aporta **contexto estructural** (callers, dependents,
-blast radius, tests) que un `Grep`/`Read` plano no puede dar.
-
----
+Regla OBLIGATORIA en todo proyecto donde el MCP `code-review-graph` esté disponible
+(herramientas `mcp__code-review-graph__*` registradas o deferred en la sesión, o
+grafo declarado en el `CLAUDE.md` del proyecto).
 
 ## Principio
 
-> Cuando necesites **explorar, entender, revisar o medir impacto** de código y
-> el grafo `code-review-graph` esté disponible, **consúltalo PRIMERO** con las
-> herramientas `mcp__code-review-graph__*`. Cae a `Read`/`Grep`/`Glob` solo
-> cuando el grafo no cubre lo que necesitas (ver excepciones), no por inercia.
-
-El costo de una consulta al grafo es de segundos y pocos tokens. El costo de
-leer 5-10 archivos completos para reconstruir relaciones que el grafo ya conoce
-es contexto desperdiciado y dinero.
-
----
-
-## Cuándo usar el grafo PRIMERO (obligatorio)
+> Para **explorar, entender, revisar o medir impacto** de código, consulta el grafo
+> PRIMERO — es más barato en tokens, más rápido y da contexto estructural (callers,
+> dependents, blast radius, tests) que un `Grep`/`Read` plano no puede dar. Cae a
+> `Read`/`Grep`/`Glob` solo cuando el grafo no cubre lo que necesitas, no por inercia.
 
-| Necesidad | Herramienta del grafo | En vez de |
-|---|---|---|
-| Encontrar una función/clase/tipo por nombre o keyword | `semantic_search_nodes_tool` | `Grep` amplio |
-| Entender la arquitectura de alto nivel | `get_architecture_overview_tool`, `list_communities_tool` | leer N archivos para inferir estructura |
-| Trazar callers / callees / imports / tests | `query_graph_tool` (patrones callers_of, callees_of, imports_of, tests_for, dependencies) | `Grep` recursivo + lectura manual |
-| Medir blast radius de un cambio | `get_impact_radius_tool` | rastrear imports a mano |
-| Saber qué flujos de ejecución afecta un cambio | `get_affected_flows_tool` | inferir leyendo |
-| Revisar cambios (code review) con riesgo puntuado | `detect_changes_tool` | `git diff` + leer archivos completos |
-| Obtener snippets justos para revisar | `get_review_context_tool`, `get_minimal_context_tool` | `Read` de archivos enteros |
-| Planear renames / detectar código muerto | `refactor_tool` | `Grep` + verificación manual |
-| Funciones grandes / hubs / puentes arquitectónicos | `find_large_functions_tool`, `get_hub_nodes_tool`, `get_bridge_nodes_tool` | heurística manual |
-| Verificar cobertura de tests de un símbolo | `query_graph_tool` pattern `tests_for` | `Grep` de nombres de test |
+## Mapa mínimo de herramientas
 
-Antes de una sesión de exploración/revisión, vale `list_graph_stats_tool` para
-confirmar que el grafo está construido y fresco (`Last updated`).
+- Buscar función/clase/tipo por nombre o keyword → `semantic_search_nodes_tool`.
+- Arquitectura de alto nivel → `get_architecture_overview_tool` / `list_communities_tool`.
+- Callers / callees / imports / tests → `query_graph_tool` (callers_of, callees_of, imports_of, tests_for).
+- Blast radius / flujos afectados → `get_impact_radius_tool` / `get_affected_flows_tool`.
+- Code review con riesgo puntuado → `detect_changes_tool` + `get_review_context_tool`.
+- Snippets justos / renames / código muerto → `get_minimal_context_tool` / `refactor_tool`.
 
----
+## Workflow
 
-## Workflow estándar
-
-1. **Localizar**: `semantic_search_nodes_tool` con el nombre/keyword del símbolo
-   o `get_architecture_overview_tool` para el mapa general.
-2. **Relacionar**: `query_graph_tool` (callers/callees/imports/tests) o
-   `get_impact_radius_tool` para el blast radius.
-3. **Leer dirigido**: `get_review_context_tool`/`get_minimal_context_tool` para
-   traer solo los snippets relevantes — no el archivo completo.
-4. **Caer al filesystem solo entonces**: si el grafo no cubre el detalle
-   concreto (líneas exactas no indexadas, archivos no parseados, formatos no
-   soportados), ahí sí `Read`/`Grep` con foco específico.
-
-El grafo se auto-actualiza vía hooks al cambiar archivos. Si `list_graph_stats`
-muestra un `Last updated` viejo respecto a cambios recientes, reconstruir con
+Localizar → relacionar → leer dirigido (`get_review_context_tool`/`get_minimal_context_tool`)
+→ filesystem solo para el detalle no cubierto. Verificar frescura con
+`list_graph_stats_tool`; si `Last updated` es viejo, reconstruir con
 `build_or_update_graph_tool` antes de confiar en sus resultados.
 
----
-
-## Cuándo SÍ usar Read/Grep/Glob directo (excepciones)
-
-NO forzar el grafo cuando:
-
-1. **El grafo no está disponible** — el proyecto no tiene `code-review-graph`
-   instalado, o `list_graph_stats_tool` falla. Usar Read/Grep sin más.
-2. **Lenguaje/formato no indexado** — el grafo parsea código fuente (Python, JS,
-   TS, Go, Rust, Java, C#, bash). Para `.md`, `.json`, `.sql`, `.yaml`, `.env`,
-   migraciones, seeds, configs → Read/Grep directo (el grafo no los modela).
-3. **Necesitas líneas exactas o contenido literal** — verificar una cita
-   `archivo:línea`, leer el cuerpo completo de un archivo que vas a editar,
-   confirmar texto exacto. El grafo da estructura, no sustituye `Read` del
-   archivo que vas a modificar.
-4. **El usuario pidió explícitamente** leer un archivo concreto o hacer un grep
-   puntual.
-5. **Operación de un solo archivo ya conocido** — sabes exactamente qué archivo
-   y qué línea; un `Read` dirigido es más simple que el grafo.
-6. **El grafo está desactualizado** para el cambio recién hecho y no quieres
-   reconstruirlo en ese instante — usa Grep para lo recién escrito.
-
-Antes de editar un archivo, SIEMPRE `Read` del archivo (la regla de Edit lo
-exige y la verificación de citas `archivo:línea` también). El grafo localiza
-**qué** leer; no reemplaza la lectura del archivo que vas a tocar.
-
----
-
-## Anti-patrones
-
-- **`Grep` amplio del codebase** para encontrar una función cuando
-  `semantic_search_nodes_tool` la ubica en una llamada.
-- **Leer 5+ archivos completos** para entender la arquitectura sin haber
-  consultado `get_architecture_overview_tool` primero.
-- **Rastrear imports a mano con `Grep`** para estimar el impacto de un cambio en
-  vez de `get_impact_radius_tool` / `get_affected_flows_tool`.
-- **`git diff` + leer archivos enteros** para revisar cuando `detect_changes_tool`
-  da el diff con riesgo puntuado y `get_review_context_tool` los snippets justos.
-- **Defaultear a Read/Grep "porque es lo de siempre"** cuando las herramientas
-  `mcp__code-review-graph__*` aparecen deferred (schemas not loaded) — deferred
-  ≠ ausente: cargar el schema con `ToolSearch(query="select:<tool>")` y usarlo.
-  Confundir "no cargado" con "no disponible" es el mismo error documentado para
-  el MCP `obsidian` en `consultar-vault-primero.md`.
-- **Confiar en el grafo sin verificar frescura** tras cambios recientes — si
-  `Last updated` es anterior al cambio, reconstruir o caer a Grep para esa parte.
-
----
-
-## Relación con otras reglas
-
-- `~/.claude/rules/consultar-vault-primero.md` — patrón hermano: consultar la
-  fuente curada (vault Obsidian para decisiones; grafo para estructura de
-  código) antes de leer múltiples archivos. Mismo principio de economía de
-  tokens y mismo anti-patrón de "deferred ≠ ausente".
-- `~/.claude/rules/verificar-citas-normativas.md § Familia 2` — el grafo
-  **localiza** la cita `archivo:línea`; verificarla aún exige `Read` del archivo
-  real. El grafo no exime de la verificación de citas.
-- `~/.claude/rules/harness-claude-code.md § Disciplina de input format` — repos
-  grandes (>500 archivos) son donde el grafo da el mayor ahorro de tokens
-  (6.8-49× por review según la nota de ese harness).
-- `~/.claude/rules/analizar-directorios-antes-de-escribir.md` — para decidir
-  DÓNDE escribir docs sigue siendo `ls`/`Glob`; el grafo es para explorar
-  **código**, no estructura de directorios de documentación.
-
----
-
-## Aplicabilidad
-
-Aplica a:
-- Claude Code (CLI, Desktop, IDE) en proyectos con `code-review-graph` activo.
-- Sesiones de exploración, debugging, code review, refactor, análisis de impacto.
+## Excepciones (Read/Grep/Glob directo, sin forzar el grafo)
 
-NO aplica a:
-- Proyectos sin el grafo instalado.
-- Exploración de documentación/configuración no indexada por el grafo.
-- Sub-agentes que operan sobre un único archivo pasado como argumento.
+1. El grafo no está disponible o `list_graph_stats_tool` falla.
+2. Formato no indexado: `.md`, `.json`, `.sql`, `.yaml`, `.env`, migraciones, seeds, configs.
+3. Necesitas líneas exactas o contenido literal — y antes de editar, SIEMPRE `Read` del archivo (el grafo localiza QUÉ leer, no sustituye la lectura de lo que vas a tocar).
+4. El usuario pidió explícitamente leer un archivo concreto o hacer un grep puntual.
+5. Operación de un solo archivo ya conocido — un `Read` dirigido es más simple.
+6. Grafo desactualizado para el cambio recién hecho — usa Grep para lo recién escrito.
 
----
+## Anti-patrón clave
 
-## Origen
+Deferred ≠ ausente: si las herramientas `mcp__code-review-graph__*` aparecen deferred
+(schemas not loaded), cargar el schema con `ToolSearch(query="select:<tool>")` y usarlas —
+NO defaultear a Grep "porque es lo de siempre".
 
-Formalizada el 2026-06-09 a petición explícita del usuario tras observar que en
-una sesión larga (feature B-1 de SIGM) se usó `Grep`/`Read`/`Bash` directo de
-forma intensiva para explorar el codebase mientras el MCP `code-review-graph`
-estaba disponible y auto-actualizado (9336 nodos, 78247 aristas). El proyecto
-SIGM ya documentaba la preferencia en su `CLAUDE.md` ("ALWAYS use the
-code-review-graph MCP tools BEFORE using Grep/Glob/Read"), pero el usuario pidió
-promoverla a regla global para que aplique a todo proyecto con el grafo, no solo
-a SIGM. La regla global es ahora la fuente de verdad del comportamiento; el
-`CLAUDE.md` de cada proyecto solo debe declarar que el grafo está disponible
-(no re-derivar el comportamiento — ver `sin-duplicacion-reglas-globales.md`).
+Detalle extendido (tabla completa de herramientas, workflow desarrollado, anti-patrones,
+relación con otras reglas, origen): `Skill("meta-reglas-extendido")` → `recursos/usar-code-review-graph.md`.