@saulwade/swl-ses 2.4.3 → 2.5.1

package/habilidades/meta-reglas-extendido/recursos/usar-code-review-graph.md

@@ -0,0 +1,156 @@
+# Usar code-review-graph antes de Read/Grep/Glob — extendido
+
+> Extendido de `reglas/usar-code-review-graph.md` (Fase D, dieta de contexto).
+> El núcleo instalado es la norma; aquí viven la tabla completa de herramientas,
+> el workflow desarrollado, las excepciones y anti-patrones completos, la
+> relación con otras reglas y el origen.
+
+## Índice
+
+- [Cuándo usar el grafo PRIMERO (obligatorio)](#cuándo-usar-el-grafo-primero-obligatorio)
+- [Workflow estándar](#workflow-estándar)
+- [Cuándo SÍ usar Read/Grep/Glob directo (excepciones)](#cuándo-sí-usar-readgrepglob-directo-excepciones)
+- [Anti-patrones](#anti-patrones)
+- [Relación con otras reglas](#relación-con-otras-reglas)
+- [Aplicabilidad](#aplicabilidad)
+- [Origen](#origen)
+
+---
+
+## Cuándo usar el grafo PRIMERO (obligatorio)
+
+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.
+
+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.
+
+| 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 |
+
+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`).
+
+---
+
+## 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
+`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.
+
+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.
+
+---
+
+## Origen
+
+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`).

package/habilidades/meta-reglas-extendido/recursos/usar-context7.md

@@ -0,0 +1,236 @@
+# Consultar Context7 — extendido
+
+> Extendido de `reglas/usar-context7.md` (Fase D, dieta de contexto). El núcleo
+> instalado es la norma; aquí viven la motivación completa, el flujo de consulta
+> con ejemplos, la tabla de aplicabilidad por agente y el caso de origen.
+
+## Índice
+
+- [Por qué existe esta regla](#por-qué-existe-esta-regla)
+- [Cuándo consultar Context7 (OBLIGATORIO)](#cuándo-consultar-context7-obligatorio)
+- [Cómo consultar Context7](#cómo-consultar-context7)
+- [Reglas estrictas](#reglas-estrictas)
+- [Excepción: Context7 no responde o no tiene la librería](#excepción-context7-no-responde-o-no-tiene-la-librería)
+- [Auditoría retroactiva](#auditoría-retroactiva)
+- [Aplicabilidad por agente](#aplicabilidad-por-agente)
+- [Checklist de consulta Context7](#checklist-de-consulta-context7)
+- [Origen de esta regla](#origen-de-esta-regla)
+
+---
+
+## Por qué existe esta regla
+
+El conocimiento del modelo sobre librerías de terceros tiene fecha de
+corte. Una librería que en el corte estaba en la versión X y era la
+recomendación, hoy puede estar:
+
+- En una versión Y mayor con cambios incompatibles
+- Deprecada y reemplazada por otra librería
+- Con vulnerabilidades conocidas que requieren un parche
+- Renombrada o migrada a otra organización
+
+Generar código sin verificar la versión actual genera tres clases de
+defectos en producción:
+
+1. **Imports a APIs deprecadas** que arrastran warnings o se eliminan
+   en próximas versiones (ejemplo histórico: `@xenova/transformers`
+   migrado a `@huggingface/transformers`).
+2. **Dependencias transitivas obsoletas** que el usuario ve como
+   warnings al instalar (ejemplo: `prebuild-install@7.1.3` arrastrada
+   por una librería que el sistema eligió sin verificar la salud).
+3. **Vulnerabilidades CVE conocidas** que están parchadas en versiones
+   más nuevas que el modelo no conoce.
+
+Context7 (MCP `mcp__claude_ai_Context7__query-docs` y
+`mcp__claude_ai_Context7__resolve-library-id`) provee documentación
+actualizada de librerías y frameworks. Su uso es la primera línea de
+defensa contra estos tres problemas.
+
+---
+
+## Cuándo consultar Context7 (OBLIGATORIO)
+
+Antes de:
+
+1. **Agregar una nueva dependencia** a `package.json`, `requirements.txt`,
+   `pom.xml`, `Cargo.toml`, `go.mod`, `composer.json`, `Package.swift` o
+   equivalente.
+2. **Generar código que importe o use una librería externa** que no
+   estaba ya en uso en el proyecto, aunque la librería ya esté
+   instalada.
+3. **Actualizar la versión** de una dependencia existente.
+4. **Migrar de una librería a otra** alternativa (ej.
+   `axios` → `fetch`, `moment` → `date-fns`, `jest` → `vitest`).
+5. **Resolver un warning de deprecación** de una dependencia
+   transitiva.
+6. **Implementar un patrón nuevo** del framework (ej. Server Actions
+   en Next.js, Signals en Angular, Suspense en React) — la API
+   correcta cambia rápido.
+
+NO es necesario consultar Context7 cuando:
+
+- La librería es interna al proyecto SWL (`scripts/lib/*`,
+  `hooks/lib/*`).
+- Es la biblioteca estándar del lenguaje (Node `fs`, Python `os`).
+- Es código que no usa dependencias externas (algoritmos, lógica de
+  negocio sin librerías de terceros).
+- El cambio es trivial (renombrar variable, formatear).
+
+---
+
+## Cómo consultar Context7
+
+El MCP de Context7 expone dos herramientas principales:
+
+```
+mcp__claude_ai_Context7__resolve-library-id(libraryName)
+  → Resuelve un nombre de librería (ej. "react", "next.js") al ID
+    canónico que Context7 usa internamente.
+
+mcp__claude_ai_Context7__query-docs(library, topic, version?)
+  → Devuelve documentación actualizada de la librería sobre el
+    topic específico. Acepta versión opcional.
+```
+
+Flujo típico:
+
+1. Resolver el ID de la librería:
+   ```
+   const id = mcp__claude_ai_Context7__resolve-library-id({
+     libraryName: "next.js"
+   });
+   ```
+
+2. Consultar el tema específico:
+   ```
+   const docs = mcp__claude_ai_Context7__query-docs({
+     library: id,
+     topic: "Server Actions",
+     version: "16"
+   });
+   ```
+
+3. Verificar:
+   - ¿La librería sigue siendo la recomendada o está deprecada?
+   - ¿Hay una alternativa migrada que deberíamos usar?
+   - ¿La API que voy a generar es la actual o cambió?
+   - ¿La versión que recomienda Context7 coincide con la del
+     `package.json` del proyecto?
+
+---
+
+## Reglas estrictas
+
+### NUNCA agregar dependencia sin verificar
+
+Antes de escribir `npm install <paquete>`, `pip install <paquete>`,
+`go get <paquete>` o equivalente:
+
+- Consultar Context7 para confirmar que la librería sigue activa.
+- Confirmar la versión más reciente compatible con el resto del
+  stack del proyecto.
+- Si Context7 reporta deprecación, **NO la uses**. Buscar la
+  alternativa migrada.
+
+### NUNCA generar código con API obsoleta
+
+Si el usuario pide implementar X usando librería Y:
+
+- Consultar Context7 sobre cómo se hace X en la versión actual de Y.
+- Si la API que aparece en el contexto del modelo difiere de la que
+  Context7 reporta como actual, **usar la de Context7**.
+- Documentar en un comentario corto la versión consultada y la
+  fecha si la API es notable.
+
+### NUNCA copiar ejemplos de la web sin verificar versión
+
+Stack Overflow, blogs y tutoriales tienen alta probabilidad de
+mostrar código deprecado. Si el agente consulta una web (vía
+WebSearch o WebFetch) y obtiene un ejemplo, ese ejemplo debe
+validarse contra Context7 antes de incorporarlo.
+
+---
+
+## Excepción: Context7 no responde o no tiene la librería
+
+Si Context7 no tiene documentación disponible para una librería
+específica:
+
+1. **Documentar en el código** que Context7 no respondió y la API se
+   tomó de la fuente oficial (npm registry, docs del repo).
+2. **Verificar al menos**: la librería existe, no está deprecada en
+   npm/PyPI, su última publicación es reciente (≤ 12 meses).
+3. **NO bloquear** el flujo del usuario por este caso — proceder con
+   diligencia razonable.
+
+---
+
+## Auditoría retroactiva
+
+Esta regla aplica también al código existente del proyecto SWL:
+
+- Si durante un refactor se detecta una dependencia que arrastra
+  warnings de deprecación, abrir un ticket para auditarla con
+  Context7 y migrar si hay alternativa actual.
+- El comando `/swl:auditar-deps` (cuando esté disponible) debe
+  cruzar las dependencias del proyecto contra Context7 para
+  detectar deprecaciones silenciosas.
+
+---
+
+## Aplicabilidad por agente
+
+| Agente | Aplica | Cuándo |
+|---|---|---|
+| `backend-python-swl` | SÍ | Al generar código FastAPI/Django/SQLAlchemy |
+| `backend-node-swl` | SÍ | Al generar código Express/Fastify/NestJS |
+| `backend-java-swl` | SÍ | Al generar código Spring Boot/JPA |
+| `backend-go-swl` | SÍ | Al generar código Go con frameworks |
+| `backend-rust-swl` | SÍ | Al generar código Axum/Actix |
+| `backend-csharp-swl` | SÍ | Al generar código ASP.NET Core |
+| `frontend-react-swl` | SÍ | Al generar código React/Next.js |
+| `frontend-angular-swl` | SÍ | Al generar código Angular |
+| `frontend-css-swl` | SÍ | Al usar PostCSS/Tailwind plugins |
+| `frontend-tailwind-swl` | SÍ | Al usar Tailwind v4+ APIs |
+| `frontend-swl` | SÍ | Al usar Vue/Svelte/Lit |
+| `mobile-android-swl` | SÍ | Al usar Jetpack Compose libs |
+| `mobile-ios-swl` | SÍ | Al usar SwiftUI/Combine |
+| `mobile-cross-swl` | SÍ | Al usar React Native/Flutter |
+| `implementador-swl` | SÍ | Generalista — siempre |
+| `llm-apps-swl` | SÍ | LangChain, OpenAI SDK, Anthropic SDK |
+| `pagos-swl` | SÍ | Stripe SDK actualizado |
+| `datos-swl` | SÍ | ORMs y drivers de BD |
+| `arquitecto-swl` | RECOMENDADO | Al evaluar tradeoffs entre librerías |
+| `revisor-codigo-swl` | RECOMENDADO | Al detectar deps deprecadas en review |
+| `revisor-seguridad-swl` | OBLIGATORIO | Al verificar CVEs de dependencias |
+| Resto de agentes | NO | No generan código con dependencias externas |
+
+---
+
+## Checklist de consulta Context7
+
+Antes de marcar una tarea como completa:
+
+- [ ] ¿Las dependencias agregadas/usadas se verificaron contra Context7?
+- [ ] ¿La versión usada está alineada con la que Context7 reporta como actual?
+- [ ] ¿No hay imports de APIs deprecadas según Context7?
+- [ ] ¿Las dependencias transitivas conocidas no son warnings de
+      deprecación al instalar?
+- [ ] Si Context7 no tenía la librería, ¿se documentó el motivo?
+
+---
+
+## Origen de esta regla
+
+Esta regla se formalizó tras observar en la primera instalación pública
+de `@saulwade/swl-ses@1.0.0` (2026-04-30) un warning de
+`prebuild-install@7.1.3 deprecated` arrastrado por
+`@xenova/transformers` que estaba en `optionalDependencies`. La
+dependencia se eligió en una iteración anterior sin verificar Context7;
+la migración oficial era `@huggingface/transformers`. El warning se vio
+en cada `npm install` del paquete distribuido. Resuelto en v1.0.1
+eliminando la dependencia opcional y elevando esta regla a obligatoria
+para que no se repita.
+
+Memoria asociada: `feedback_usar_context7.md` (preferencia previa del
+usuario, formalizada como regla).

package/habilidades/meta-reglas-extendido/recursos/usar-sistema-swl.md

@@ -0,0 +1,253 @@
+# Uso obligatorio del sistema SWL — extendido
+
+> Extendido de `reglas/usar-sistema-swl.md` (Fase D, dieta de contexto). El núcleo
+> instalado es la norma — su matriz operacional comprimida es LA herramienta de
+> decisión; aquí viven el racional completo, la matriz con justificaciones, los
+> anti-patrones desarrollados con MAL/BIEN y los checklists íntegros.
+
+## Índice
+
+- [Por qué existe esta regla](#por-qué-existe-esta-regla)
+- [Matriz operacional completa](#matriz-operacional-completa)
+- [Excepciones legítimas](#excepciones-legítimas)
+- [Anti-patrones explícitos](#anti-patrones-explícitos)
+- [Checklist antes de empezar cualquier tarea](#checklist-antes-de-empezar-cualquier-tarea)
+- [Cómo recuperarse si ya empecé directo](#cómo-recuperarse-si-ya-empecé-directo)
+- [Aplicabilidad](#aplicabilidad)
+- [Relación con otras reglas](#relación-con-otras-reglas)
+- [Checklist de auto-verificación al final del turno](#checklist-de-auto-verificación-al-final-del-turno)
+
+---
+
+## Por qué existe esta regla
+
+El sistema SWL se instaló específicamente para que Claude **no haga trabajo
+directo cuando hay un componente especializado**. El patrón recurrente que
+esta regla cierra es:
+
+- Implementar con Read/Write/Edit en vez de invocar `implementador-swl` o el
+  agente de stack (`backend-python-swl`, `frontend-react-swl`, etc.).
+- Hacer commits sin invocar `revisor-codigo-swl` ni `revisor-seguridad-swl`.
+- Escribir código sin cargar el skill de stack correspondiente
+  (`fastapi-experto`, `react-experto`, `angular-moderno`).
+- Implementar features sin pasar por `/swl:discutir-fase` → `/swl:planear-fase`
+  → `/swl:ejecutar-fase` cuando el alcance lo justifica.
+- Diferir scope (entregar read-only cuando el plan decía CRUD) sin invocar al
+  planificador ni crear DA formal — viola `arreglar-al-detectar.md`.
+
+El patrón es costoso y reproducible. La regla `arreglar-al-detectar.md`
+prohíbe la deuda silenciosa; esta regla cierra la causa raíz: saltarse el
+flujo SWL desde el inicio.
+
+El sistema SWL es la herramienta del usuario — saltársela sin justificación
+es decisión que la regla `debatir-antes-de-aceptar.md` exige debatir antes
+de ejecutar.
+
+---
+
+## Matriz operacional completa
+
+Versión íntegra de la matriz del núcleo, con la columna que justifica por qué
+el trabajo directo NO basta.
+
+### Para tareas de desarrollo
+
+| Tarea | Componente SWL obligatorio | Componente directo NO basta porque |
+|---|---|---|
+| Feature nueva > 50 LOC o multi-archivo | `/swl:discutir-fase` → `/swl:planear-fase` → `/swl:ejecutar-fase` o `orquestador-swl` | Sin discovery el scope queda implícito y diverge en ejecución |
+| Implementación backend Python/Node/Java/Go/Rust/C# | `backend-python-swl` / `backend-node-swl` / etc. + `Skill("<framework>-experto")` | El skill carga gotchas críticos (ej: MissingGreenlet en SQLAlchemy async) |
+| Implementación frontend React/Angular/Vue/Svelte | `frontend-react-swl` / `frontend-angular-swl` / `frontend-swl` + skill correspondiente | Los skills traen patrones modernos (signals, RSC, Suspense) que el modelo no actualiza solo |
+| Implementación mobile Android/iOS/RN/Flutter | `mobile-android-swl` / `mobile-ios-swl` / `mobile-cross-swl` | Casos edge de plataforma (Core Data, baseline profiles) |
+| Bug con stack trace o reproducible | `depurador-swl` con método científico | Saltar al fix sin hipótesis aislada falla con frecuencia |
+| Refactor masivo o migración schema | `migrador-swl` | Exige plan de rollback + expand-contract, no improvisar |
+
+### Para tareas de calidad
+
+| Tarea | Componente SWL obligatorio |
+|---|---|
+| Pre-merge a main | `/swl:revisar` o `revisor-codigo-swl` + `revisor-seguridad-swl` |
+| Verificación post-fase | `/swl:verificar` con `Skill("verificar-trabajo")` (goal-backward 4 niveles) |
+| Auditoría de calidad | `Skill("checklist-calidad")` con score ≥9.0 |
+| Tests nuevos | `tdd-qa-swl` (ciclo RED→GREEN→REFACTOR) |
+| Auditoría de seguridad | `Skill("checklist-seguridad")` (OWASP Top 10 + A11) |
+| Detectar funcionalidad duplicada | `Skill("swl-revisar-impacto")` o `revisor-codigo-swl` con veto DRY mayor |
+
+### Para tareas de proceso
+
+| Tarea | Componente SWL obligatorio |
+|---|---|
+| Cierre de sesión productiva | `/swl:compactar` + `/swl:aprender` |
+| Capturar aprendizaje recurrente | `/swl:aprender` → APRENDIZAJES.md → posible promoción a regla/skill |
+| Release con bump de versión | `/swl:release` (sincronización de ubicaciones de versión) |
+| Documentación viva post-feature | `documentador-swl` |
+| Diagnóstico del sistema | `/swl:status salud` |
+
+### Para tareas de búsqueda y contexto
+
+| Tarea | Componente SWL obligatorio |
+|---|---|
+| Contexto de dominio previo | `Skill("memoria-busqueda")` sobre `.planning/sessions/` y APRENDIZAJES.md |
+| Investigación tecnológica | `investigador-swl` con WebSearch/WebFetch + `Skill("agent-browser")` |
+| Verificar dependencia externa | Consultar Context7 (regla `usar-context7.md`) |
+| Decisiones repetibles del proyecto | Revisar `.planning/adrs/`, APRENDIZAJES.md, `instintos/proyecto.yaml` ANTES de proponer solución |
+
+---
+
+## Excepciones legítimas
+
+NO aplicar esta regla cuando:
+
+1. **Tarea trivial de 1-2 archivos**: rename, fix de typo, ajuste de comentario,
+   formato. El overhead de invocar agente supera el valor.
+2. **Pregunta de lectura pura**: "¿qué hace este archivo?", "¿dónde se define
+   X?". Usar Read/Grep directos.
+3. **Comando de shell puro**: `git status`, `npm install`, `gh pr list`.
+4. **Sesión exploratoria explícita**: el usuario pidió "explora", "echa un
+   vistazo", "investiga sin tocar nada".
+5. **Override explícito del usuario**: "no uses agentes, hazlo directo".
+   Respetar la instrucción explícita; registrar la excepción si tiene impacto
+   en flujo posterior.
+6. **Fix urgente de producción** con incidente activo: aplicar fix mínimo,
+   el agente puede esperar al post-mortem.
+7. **Proyecto sin SWL instalado**: si no hay `plugin.json` ni `agentes/` en
+   el proyecto, la regla no aplica.
+
+---
+
+## Anti-patrones explícitos
+
+### Anti-patrón 1: implementar feature compleja con Read+Write directo
+
+❌ **MAL**: el usuario pide "agrega CRUD para entidad X", Claude empieza a
+escribir el modelo + endpoint + frontend + tests con Read+Write secuenciales,
+sin pasar por `/swl:planear-fase` ni invocar `backend-python-swl`.
+
+✅ **BIEN**: invocar `/swl:discutir-fase` para extraer decisiones,
+`/swl:planear-fase` para descomponer en tareas atómicas, `/swl:ejecutar-fase`
+que delega a `implementador-swl` o agente de stack con skill cargado.
+
+### Anti-patrón 2: commit sin revisión
+
+❌ **MAL**: terminar implementación y hacer `git add . && git commit` sin
+pasar por `revisor-codigo-swl` ni `revisor-seguridad-swl`.
+
+✅ **BIEN**: `/swl:revisar` antes del commit. Score ≥ 9.0 obligatorio. Si
+hay veto items, corregir antes de mergear.
+
+### Anti-patrón 3: divergir del plan sin reconfirmar scope
+
+❌ **MAL**: plan decía "CRUD completo", entregar read-only documentando en
+commit "la edición se agrega en iteración posterior". Es deuda silenciosa
+prohibida por `arreglar-al-detectar.md`.
+
+✅ **BIEN**: si durante ejecución se detecta que el scope original es muy
+grande, pausar, invocar `planificador-swl` para re-planificar, o crear DA
+formal con trigger verificable. NUNCA diferir scope en commit silencioso.
+
+### Anti-patrón 4: implementar con framework sin cargar el skill correspondiente
+
+❌ **MAL**: escribir FastAPI con SQLAlchemy async sin cargar
+`Skill("fastapi-experto")` — alta probabilidad de incurrir en MissingGreenlet
+por lazy loading.
+
+✅ **BIEN**: cargar el skill ANTES de la primera línea. El skill trae los
+gotchas específicos que el modelo no recuerda solo.
+
+### Anti-patrón 5: detectar funcionalidad duplicada y commitearla igual
+
+❌ **MAL**: durante implementación detectar que `/catalogos` ya tiene lo
+mismo que se está agregando en `/catalogos-contratacion` pero commitearlo
+porque "el plan decía implementarlo aquí". Pérdida de DRY.
+
+✅ **BIEN**: pausar, invocar `revisor-codigo-swl` o `Skill("swl-revisar-impacto")`,
+reportar la duplicación al usuario, esperar decisión de scope.
+
+### Anti-patrón 6: usar agente especializado como "etiqueta cosmética"
+
+❌ **MAL**: decir "estoy invocando implementador-swl" pero seguir trabajando
+con Read+Write+Edit personalmente sin lanzar el Agent tool.
+
+✅ **BIEN**: invocación real con el tool Agent. El sub-agente recibe contexto
+acotado, opera con sus permisos declarados y devuelve resultado.
+
+---
+
+## Checklist antes de empezar cualquier tarea
+
+Antes de la primera tool call sustantiva:
+
+- [ ] **PASO 0 — Consultar memoria previa** (`Skill("memoria-busqueda")`,
+      APRENDIZAJES.md, `.planning/adrs/`, vault Obsidian si aplica). El
+      proyecto tiene decisiones ya tomadas y patrones validados que se
+      repiten. Empezar sin consultar es reabrir decisiones cerradas.
+- [ ] ¿La tarea cabe en alguna fila de la **matriz operacional**?
+- [ ] Si sí: ¿identifiqué el agente, skill o comando SWL correspondiente?
+- [ ] ¿Cargué el skill relevante con `Skill("nombre")` antes de implementar?
+- [ ] Si la tarea es no trivial: ¿pasó por el flujo discutir → planear → ejecutar?
+- [ ] Si voy a hacer trabajo directo: ¿estoy dentro de las **excepciones
+      legítimas**? Si no, esta regla me obliga a usar el componente SWL.
+- [ ] Antes de commit: ¿pasé por revisor de código + seguridad?
+
+---
+
+## Cómo recuperarse si ya empecé directo
+
+Si avancé con trabajo directo y al revisar esta regla detecto que debí usar
+un componente SWL:
+
+1. **Trabajo trivial y reversible**: aceptar el atajo, registrar la
+   excepción mentalmente, terminar.
+2. **Trabajo sustantivo pero sin commit**: invocar el componente SWL ahora
+   (revisor / verificar / planificador retrospectivo) antes del commit. Aún
+   se gana cobertura.
+3. **Ya se commiteó**: ejecutar `/swl:verificar` post-hoc. Si encuentra
+   hallazgos, corregir en commit siguiente bajo `arreglar-al-detectar.md`.
+4. **El patrón se repite en la sesión**: invocar `/swl:aprender` para
+   capturar el feedback explícitamente y reforzar el comportamiento futuro.
+
+---
+
+## Aplicabilidad
+
+Aplica a:
+
+- Claude Code (CLI, Desktop, IDE) operando dentro de proyectos con SWL
+  instalado.
+- Sesiones de implementación, debugging, refactor, revisión, planning.
+- Cualquier ciclo GSD (Goal-Seeking Development).
+
+NO aplica a:
+
+- Proyectos sin SWL instalado.
+- Repos de terceros, exploración de código ajeno (`temp/`, dependencias
+  npm/pip).
+- Tareas administrativas puras del sistema (instalar SWL, configurar Claude
+  Code).
+
+---
+
+## Relación con otras reglas
+
+- `arreglar-al-detectar.md` — la deuda silenciosa de scope (anti-patrón 3
+  aquí) es exactamente lo que prohíbe esa regla.
+- `debatir-antes-de-aceptar.md` — saltarse SWL sin justificación es decisión
+  que choca con regla documentada → exige debate, no ejecución silenciosa.
+- `brevedad-output.md` — cubre idioma y eficiencia de tokens; esta regla
+  cubre flujo de trabajo.
+- `skills-estandar.md` — cubre cómo escribir skills (autor); esta regla
+  cubre cómo usarlos (consumidor).
+- `usar-context7.md` — regla hermana: consultar documentación de librerías
+  externas antes de implementar.
+
+---
+
+## Checklist de auto-verificación al final del turno
+
+Al cerrar un turno con trabajo sustantivo:
+
+- [ ] ¿Invoqué los agentes/skills/comandos SWL aplicables o estuve dentro
+      de las excepciones legítimas?
+- [ ] Si hice trabajo directo: ¿la decisión está justificada por una
+      excepción concreta, no por inercia?
+- [ ] Si detecto que omití un componente que debí usar: ¿lo invoco
+      retrospectivamente antes del commit final?