# Regla: Uso obligatorio del sistema SWL

Esta regla es **OBLIGATORIA** y aplica a todo trabajo de Claude dentro de
cualquier proyecto donde el sistema SWL esté instalado (presencia de
`agentes/`, `habilidades/`, `comandos/swl/`, `reglas/` o `plugin.json` con
`name: "@saulwade/swl-ses"`).

Tiene prioridad sobre la inercia natural del modelo a hacer trabajo directo
con Read/Write/Edit/Bash cuando existe un agente, skill o comando SWL
específico para la tarea.

---

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

---

## Principio

> Cuando exista un agente, skill o comando SWL aplicable a la tarea actual,
> **usarlo es obligatorio**. Hacer trabajo directo con herramientas básicas
> (Read/Write/Edit/Bash/Grep/Glob) cuando un componente especializado lo
> cubre mejor es violación de esta regla.

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: cuándo usar qué

### 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: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?
