@saulwade/swl-ses 1.3.7 → 1.4.0

package/reglas/usar-sistema-swl.md

@@ -0,0 +1,251 @@
+# 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?

package/schemas/diary-entry.schema.json

@@ -1,80 +1,80 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://swl-ses.dev/schemas/diary-entry.json",
-  "title": "SWL Diary Entry",
-  "description": "Diario estructurado por sesion. Captura logros, decisiones, challenges y aprendizajes clave en formato consumible por /swl:aprender.",
-  "type": "object",
-  "required": ["id", "sessionId", "date", "createdAt"],
-  "properties": {
-    "id": {
-      "type": "string",
-      "pattern": "^diary-\\d{8}-[a-f0-9]+$",
-      "description": "ID unico del diario: diary-YYYYMMDD-{hash}"
-    },
-    "sessionId": {
-      "type": "string",
-      "minLength": 1,
-      "description": "ID de la sesion de Claude Code que origina el diario"
-    },
-    "agent": {
-      "type": ["string", "null"],
-      "description": "Agente principal de la sesion (si aplica)"
-    },
-    "date": {
-      "type": "string",
-      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
-      "description": "Fecha de la sesion en formato YYYY-MM-DD"
-    },
-    "startTime": {
-      "type": ["string", "null"],
-      "format": "date-time",
-      "description": "Inicio de la sesion en ISO 8601"
-    },
-    "endTime": {
-      "type": ["string", "null"],
-      "format": "date-time",
-      "description": "Fin de la sesion en ISO 8601 (null si esta abierta)"
-    },
-    "accomplishments": {
-      "type": "array",
-      "maxItems": 20,
-      "items": { "type": "string", "maxLength": 500 },
-      "description": "Logros concretos de la sesion"
-    },
-    "decisions": {
-      "type": "array",
-      "maxItems": 20,
-      "items": { "type": "string", "maxLength": 500 },
-      "description": "Decisiones tomadas con su justificacion breve"
-    },
-    "challenges": {
-      "type": "array",
-      "maxItems": 20,
-      "items": { "type": "string", "maxLength": 500 },
-      "description": "Bloqueos o problemas encontrados"
-    },
-    "keyLearnings": {
-      "type": "array",
-      "maxItems": 20,
-      "items": { "type": "string", "maxLength": 500 },
-      "description": "Aprendizajes clave que alimentan APRENDIZAJES.md o instintos"
-    },
-    "tags": {
-      "type": "array",
-      "maxItems": 20,
-      "items": { "type": "string", "maxLength": 500 },
-      "description": "Etiquetas para clasificacion y busqueda"
-    },
-    "sourceAgents": {
-      "type": "array",
-      "uniqueItems": true,
-      "items": { "type": "string" },
-      "description": "Agentes que contribuyeron a la sesion (cross-agent enrichment)"
-    },
-    "createdAt": {
-      "type": "string",
-      "format": "date-time",
-      "description": "Timestamp de creacion del diario"
-    }
-  }
-}
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://swl-ses.dev/schemas/diary-entry.json",
+  "title": "SWL Diary Entry",
+  "description": "Diario estructurado por sesion. Captura logros, decisiones, challenges y aprendizajes clave en formato consumible por /swl:aprender.",
+  "type": "object",
+  "required": ["id", "sessionId", "date", "createdAt"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^diary-\\d{8}-[a-f0-9]+$",
+      "description": "ID unico del diario: diary-YYYYMMDD-{hash}"
+    },
+    "sessionId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "ID de la sesion de Claude Code que origina el diario"
+    },
+    "agent": {
+      "type": ["string", "null"],
+      "description": "Agente principal de la sesion (si aplica)"
+    },
+    "date": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "Fecha de la sesion en formato YYYY-MM-DD"
+    },
+    "startTime": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "description": "Inicio de la sesion en ISO 8601"
+    },
+    "endTime": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "description": "Fin de la sesion en ISO 8601 (null si esta abierta)"
+    },
+    "accomplishments": {
+      "type": "array",
+      "maxItems": 20,
+      "items": { "type": "string", "maxLength": 500 },
+      "description": "Logros concretos de la sesion"
+    },
+    "decisions": {
+      "type": "array",
+      "maxItems": 20,
+      "items": { "type": "string", "maxLength": 500 },
+      "description": "Decisiones tomadas con su justificacion breve"
+    },
+    "challenges": {
+      "type": "array",
+      "maxItems": 20,
+      "items": { "type": "string", "maxLength": 500 },
+      "description": "Bloqueos o problemas encontrados"
+    },
+    "keyLearnings": {
+      "type": "array",
+      "maxItems": 20,
+      "items": { "type": "string", "maxLength": 500 },
+      "description": "Aprendizajes clave que alimentan APRENDIZAJES.md o instintos"
+    },
+    "tags": {
+      "type": "array",
+      "maxItems": 20,
+      "items": { "type": "string", "maxLength": 500 },
+      "description": "Etiquetas para clasificacion y busqueda"
+    },
+    "sourceAgents": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "type": "string" },
+      "description": "Agentes que contribuyeron a la sesion (cross-agent enrichment)"
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Timestamp de creacion del diario"
+    }
+  }
+}