@saulwade/swl-ses 1.6.1 → 1.6.5

package/habilidades/proceso-confianza-pre-implementacion/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: proceso-confianza-pre-implementacion
+description: >
+  Evaluación de confianza pre-implementación con scoring de 5 dimensiones
+  (sin duplicación 25%, cumplimiento de arquitectura 25%, docs oficiales 20%,
+  referencias OSS 15%, causa raíz identificada 15%) y umbrales 0.9 / 0.7 / <0.7.
+  Cargar antes de escribir la primera línea de una feature, refactor o fix no
+  trivial — especialmente cuando la tarea cruza >1 archivo o introduce un patrón
+  nuevo. Adaptación del patrón ConfidenceChecker de SuperClaude_Framework.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep, Glob, Bash]
+exclusiones:
+  - "No cargar para fixes triviales (typo, rename, comentario) — el overhead supera el valor."
+  - "No cargar cuando ya se ejecutó `/swl:discutir-fase` y existe `CONTEXTO.md` con decisiones cerradas — ese flujo ya cubre la verificación previa."
+  - "No cargar para tareas exploratorias (`/swl:explorar`, scouting de codebase) donde el objetivo es entender, no implementar."
+  - "No cargar para fixes urgentes de producción con incidente activo — aplicar fix mínimo, este protocolo queda para el post-mortem."
+evolvable: true
+---
+
+# Habilidad: Evaluación de confianza pre-implementación
+
+## Propósito
+
+Detener el "wrong-direction execution" antes de empezar. El costo de implementar
+una solución incorrecta supera siempre el costo de la verificación previa: el
+material analizado (SuperClaude_Framework `pm_agent/confidence.py`) reporta
+ROI **25-250×** en token savings cuando este check detiene una iteración
+equivocada. SWL ya tiene la regla `analisis-previo-tareas-grandes.md` con el
+espíritu correcto; este skill la operacionaliza con scoring objetivo y umbrales
+de acción.
+
+## Cuándo cargar
+
+- Antes de escribir la primera línea de una feature nueva > 50 LOC.
+- Antes de un refactor que cruza >1 archivo o >1 módulo.
+- Antes de fix de bug donde la causa raíz no está identificada todavía.
+- Antes de adoptar una librería externa nueva.
+- Cuando el usuario dice "implementa X" sin contexto previo y el agente
+  no tiene certeza ≥90% de qué hacer.
+
+## Cuándo NO cargar
+
+Listado en el campo `exclusiones` del frontmatter — incluye fixes triviales,
+fases con `CONTEXTO.md` ya cerrado, tareas exploratorias e incidentes
+urgentes.
+
+---
+
+## Protocolo de evaluación (5 checks ponderados)
+
+Antes de tocar código, el agente responde estos 5 checks. Cada uno aporta una
+porción del score total (0.0 a 1.0).
+
+### Check 1 — Sin duplicación (peso 0.25)
+
+¿Existe ya en el codebase una función, clase, módulo o utilidad que resuelva
+el mismo problema?
+
+- Ejecutar `Grep` con palabras clave del nombre tentativo de la nueva entidad.
+- Revisar `INVENTARIO.md` para componentes SWL ya registrados.
+- Buscar imports/usos que sugieran que ya hay solución.
+
+**Pasa** si la búsqueda confirma que no existe equivalente o el equivalente
+está deprecado/marcado para eliminación. **No pasa** si hay duda o si existe
+algo que con extensión menor cubriría el caso.
+
+### Check 2 — Cumplimiento de arquitectura (peso 0.25)
+
+¿La solución propuesta usa el stack y los patrones ya definidos del proyecto?
+
+- Leer `CLAUDE.md` del proyecto (sección "Stack" y "Convenciones").
+- Revisar ADRs vigentes (`docs/adr/` o `.planning/adrs/`).
+- Verificar reglas globales (`~/.claude/rules/`) y del proyecto (`reglas/`).
+
+**Pasa** si la solución se alinea con el stack declarado y no contradice
+ningún ADR vigente. **No pasa** si introduce dependencia nueva no justificada,
+si rompe una invariante documentada o si elige un patrón distinto al que el
+proyecto ya estandariza para el mismo problema.
+
+### Check 3 — Documentación oficial verificada (peso 0.20)
+
+¿Se consultó documentación oficial actualizada de la librería/API/patrón
+relevante?
+
+- Para librerías de terceros: regla `usar-context7.md` obliga consultar
+  Context7 antes de generar código que las use.
+- Para APIs internas: leer el módulo objetivo, no asumir su contrato por
+  el nombre.
+- Para patrones del framework: documentación oficial vigente (no copiar
+  ejemplos de StackOverflow sin verificar versión).
+
+**Pasa** si la doc oficial está leída y la API/patrón coincide con lo
+planeado. **No pasa** si se asume la API por memoria del modelo o si la
+documentación está desactualizada.
+
+### Check 4 — Referencia OSS funcional (peso 0.15)
+
+¿Existe una implementación open-source madura que resuelva el problema y
+se haya consultado?
+
+- Buscar en repos de referencia (`temp/`, `respositorios-git/`, GitHub).
+- Si hay implementación OSS validada, su patrón es la base; SWL adapta,
+  no reescribe.
+- Si no hay OSS de referencia, documentar **por qué** se prefiere solución
+  custom.
+
+**Pasa** si se identificó OSS de referencia o se justificó la ausencia.
+**No pasa** si simplemente no se buscó.
+
+### Check 5 — Causa raíz identificada (peso 0.15)
+
+Aplicable a bugfixes y refactors motivados por un problema observado.
+¿Se identificó la causa raíz con certeza, o se está parchando un síntoma?
+
+- Reproducir el bug en localhost o con test mínimo.
+- Aislar la línea/función responsable, no solo el módulo.
+- Verificar que la solución elimina la causa, no esconde el síntoma.
+
+**Pasa** si la causa raíz está localizada con archivo:línea o función
+específica, sin lenguaje vago ("posiblemente", "creo que", "tal vez").
+**No pasa** si hay incertidumbre o si el fix es "agregar try/catch para que
+no falle".
+
+Para tareas que no son bugfix (features nuevas, refactors planeados),
+este check se da por pasado automáticamente — pero documentar en el
+output que "no aplica causa raíz, es trabajo nuevo".
+
+---
+
+## Umbrales y acción recomendada
+
+Tras sumar los pesos de los checks que pasan:
+
+| Score | Nivel | Acción |
+|---|---|---|
+| **≥ 0.9** | Alta confianza | Proceder con la implementación. La inversión de los checks ya está pagada. |
+| **0.7 – 0.89** | Media confianza | **No implementar todavía**. Presentar al usuario las opciones específicas que cierran los gaps. Esperar elección. |
+| **< 0.7** | Baja confianza | **DETENERSE**. La investigación está incompleta. Volver a investigar — no implementar bajo este nivel. |
+
+El skill `analisis-previo-tareas-grandes` aplica cuando el score es 0.7-0.89
+y la tarea es grande: produce tabla comparativa + 3 opciones para el usuario.
+
+---
+
+## Formato de reporte obligatorio
+
+Antes de cualquier escritura de código, emitir al usuario (o registrar en
+`.planning/sessions/`) el siguiente formato:
+
+```
+### Confianza pre-implementación
+
+- ✅/❌ Check 1 — Sin duplicación: <descripción de qué se buscó y resultado>
+- ✅/❌ Check 2 — Arquitectura: <ADRs/reglas/stack verificados>
+- ✅/❌ Check 3 — Docs oficiales: <fuente consultada o "no aplica">
+- ✅/❌ Check 4 — Referencia OSS: <repo/módulo de referencia o justificación>
+- ✅/❌ Check 5 — Causa raíz: <archivo:línea o "no aplica (trabajo nuevo)">
+
+**Score**: 0.XX
+**Nivel**: Alto / Medio / Bajo
+**Acción**: <Procedo / Presento opciones / Detengo y re-investigo>
+```
+
+El reporte NO es opcional cuando el skill se carga. Si el agente decide
+saltarlo "por brevedad", está violando el contrato del skill — y la regla
+`debatir-antes-de-aceptar.md` exige justificar la omisión, no esquivarla.
+
+---
+
+## Reglas obligatorias
+
+1. **Score honesto**: no inflar checks "para superar el umbral". Si un check
+   no se hizo, marcar ❌. **Por qué**: inflar destruye el ROI del 25-250× —
+   un score artificial alto hace que el agente proceda con baja confianza
+   real, y el costo de la corrección posterior anula el ahorro.
+
+2. **Reportar antes de implementar**: el reporte se entrega ANTES del primer
+   `Write` o `Edit`, no después. **Por qué**: si se reporta después es
+   justificación, no verificación.
+
+3. **No saltar checks "porque obvio"**: el Check 1 (duplicación) es el más
+   tentador de saltar porque "obvio que no existe". `Grep` es de 2 segundos;
+   la duplicación silenciosa cuesta horas (ver `arreglar-al-detectar.md`).
+
+4. **Lenguaje específico, no vago**: cuando se marca ✅ un check, decir QUÉ
+   se verificó. "Grep en `backend/auth/` con patrón `verifyToken` — 0
+   resultados" es válido. "Revisé que no existe" no.
+
+5. **Si el usuario insiste en proceder con score bajo**, la regla
+   `debatir-antes-de-aceptar.md` aplica: presentar el costo conocido,
+   esperar confirmación informada, registrar la excepción en la sesión.
+   No proceder silenciosamente.
+
+---
+
+## Relación con otras herramientas SWL
+
+- **Skill `analisis-previo-tareas-grandes` (regla global)**: cubre el caso
+  específico de tarea grande con score 0.7-0.89. Produce tabla comparativa
+  y 3 opciones. Este skill (confianza pre-implementación) es más general:
+  cubre cualquier tarea no trivial.
+- **Skill `proceso-autoverificacion-evidencias`**: aplica al CIERRE del
+  trabajo (post-implementación), con las Four Questions. Este skill aplica
+  al INICIO.
+- **Skill `discutir-fase`**: cuando hay HOJA-RUTA.md y CONTEXTO.md formal,
+  ese flujo absorbe el rol de este skill — no cargar ambos.
+- **Regla `verificar-citas-normativas.md`**: aplica a citas verificables
+  durante el trabajo. Este skill aplica al inicio del trabajo.
+- **Skill `confidence-check` (oficial SuperClaude)**: si SuperClaude está
+  instalado en el sistema, el skill oficial coexiste. Este skill SWL es
+  la versión integrada con el resto del flujo SWL (CONTEXTO.md, ADRs,
+  `_userland/`, `arreglar-al-detectar.md`). Preferir el SWL dentro de
+  proyectos SWL.
+
+---
+
+## Ejemplo de uso
+
+Usuario: *"implementa un endpoint POST /facturas/cancelar"*.
+
+Agente carga este skill antes del primer `Write`:
+
+```
+### Confianza pre-implementación
+
+- ✅ Check 1 — Sin duplicación: Grep "cancelar.*factura" en backend/app/ → 0 resultados.
+  No existe endpoint equivalente. INVENTARIO.md confirma sin overlap.
+- ✅ Check 2 — Arquitectura: CLAUDE.md confirma FastAPI + SQLAlchemy async.
+  ADR-0008 establece convención de endpoints "/recursos/accion" para
+  acciones que no mapean a CRUD. Esta solución cumple.
+- ✅ Check 3 — Docs oficiales: leí docs/endpoints-existentes/facturas.md;
+  el modelo Factura ya tiene método `puede_cancelarse()`.
+- ❌ Check 4 — Referencia OSS: no busqué; es lógica de negocio interna.
+  Justificación: no aplica patrón OSS estándar — es flujo del dominio.
+- ✅ Check 5 — Causa raíz: no aplica (trabajo nuevo, no bugfix).
+
+**Score**: 0.85 (5×0.25+0.20+0+0.15 = pasan 4 de 5, falla Check 4
+con justificación aceptable)
+**Nivel**: Medio (0.7-0.89)
+**Acción**: Presento opciones al usuario antes de implementar.
+
+¿Procedo con la implementación directa, o prefieres que valide primero
+con un test de aceptación escrito (TDD)?
+```
+
+El usuario decide, no el agente. Score medio → preguntar.

package/habilidades/proceso-ddia-fundamentos/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: proceso-ddia-fundamentos
+description: >
+  Conceptos fundamentales del libro "Designing Data-Intensive Applications" de
+  Martin Kleppmann aplicables a sistemas no-distribuidos (como SWL): Cap 1
+  Reliability/Scalability/Maintainability como framework de evaluación, Cap 4
+  Schema Evolution con backward/forward compatibility, Cap 12 End-to-End
+  Argument y Trust-but-Verify. Cargar al diseñar manifiestos versionados,
+  evaluar arquitectura de un módulo, decidir dónde validar correctitud.
+when_to_use: >
+  Usar cuando el usuario menciona schema versioning, backward/forward compat,
+  end-to-end verification, trust but verify, reliability scalability
+  maintainability, RSM framework, Operability Simplicity Evolvability,
+  schema-evolution, evaluar arquitectura, decidir dónde validar.
+---
+
+# DDIA Fundamentos — RSM, Schema Evolution, End-to-End
+
+Adaptado de Martin Kleppmann, *"Designing Data-Intensive Applications"*
+(O'Reilly, 2017). Skill cubre los tres ejes del libro que aplican a SWL:
+
+- **Capítulo 1** — Reliability, Scalability, Maintainability como framework.
+- **Capítulo 4** — Schema Evolution (back/forward compatibility).
+- **Capítulo 12** — End-to-End Argument + Trust-but-Verify.
+
+Los demás capítulos del libro (2-3 data models / storage, 5-10 distributed
+systems) tratan dominios que SWL no es (no es BD, no es sistema distribuido).
+Se descartan por filtro de dominio (regla `arquitectura.md`).
+
+## Cuándo cargar
+
+- Diseñar un schema nuevo (manifest, frontmatter, JSON Schema) que
+  evolucionará en el tiempo.
+- Auditar un módulo SWL para evaluar Reliability/Scalability/Maintainability.
+- Decidir dónde poner una validación: en cada capa o solo end-to-end.
+- Resolver una duda sobre "¿esto se rompe si actualizo el sistema?" — es
+  pregunta de schema compatibility.
+
+## Cuándo NO cargar
+
+- Discusiones sobre replication, partitioning, consenso (Paxos/Raft) — esos
+  capítulos DDIA no aplican a SWL.
+- Streaming/event sourcing avanzado — cargar `Skill("proceso-ddia-streaming")`.
+- Optimización puntual de query SQL — cargar `Skill("performance-baseline")`.
+
+---
+
+## Parte 1 — Reliability, Scalability, Maintainability (RSM)
+
+Cita textual del libro (DDIA p.18, línea 1411-1453):
+
+> "It is well known that the majority of the cost of software is not in its
+> initial development, but in its ongoing maintenance — fixing bugs, keeping
+> its systems operational, investigating failures, adapting it to new
+> platforms, modifying it for new use cases, repaying technical debt, and
+> adding new features."
+
+### Las 3 dimensiones del RSM
+
+**Reliability** — el sistema sigue funcionando correctamente bajo:
+- Hardware faults
+- Software errors
+- Human errors
+
+Tipos de respuesta:
+- **Fault-tolerant**: el sistema absorbe la falla sin propagarla.
+- **Resilient**: degrada con gracia, no en cascada.
+
+**Aplicación a SWL**: hooks bloqueantes (`calidad-pre-commit`,
+`escaneo-secretos`) son fault-tolerance. Las escrituras atómicas
+(`hooks/lib/atomic-write.js`) son resilience contra crashes durante write.
+
+**Scalability** — cómo cambia el rendimiento cuando crece la carga:
+- Describir **carga** (parámetros: throughput, concurrent users, etc.)
+- Describir **rendimiento** (latencia: p50, p95, p99)
+
+**Aplicación a SWL**: las métricas `Skill("performance-baseline")` siguen
+este modelo. Carga = sesiones concurrentes, archivos por proyecto, agentes
+en cadena. Rendimiento = latencia de hooks, tiempo de respuesta de
+validadores.
+
+**Maintainability** — tres principios de diseño del libro:
+
+> "Operability: Make it easy for operations teams to keep the system running
+> smoothly.
+> Simplicity: Make it easy for new engineers to understand the system, by
+> removing as much complexity as possible from the system. (Note this is
+> not the same as simplicity of the user interface.)
+> Evolvability: Make it easy for engineers to make changes to the system in
+> the future, adapting it for unanticipated use cases as requirements
+> change. Also known as extensibility, modifiability, or plasticity."
+> (DDIA p.18-19, líneas 1435-1449)
+
+**Aplicación a SWL**:
+
+| Principio DDIA | Implementación SWL |
+|---|---|
+| Operability | `/swl:salud`, `/swl:dashboard`, `/swl:doctor`, runbooks |
+| Simplicity | Skills ≤300 líneas, módulos profundos (Ousterhout), zero-deps en `hooks/lib/` |
+| Evolvability | ADRs versionados, schemas opcionales aditivos, fragments compartidos |
+
+### Cómo usar RSM como rúbrica de evaluación
+
+Antes de declarar un módulo "listo", pregúntate:
+
+1. **Reliability**: ¿qué pasa si una entrada inesperada llega? ¿Si un hook
+   externo falla? ¿Si el filesystem se llena?
+2. **Scalability**: ¿el módulo escala con el tamaño del proyecto del
+   usuario? Si tiene 1000 archivos vs 10, ¿degrada linealmente o se
+   cuadratiza?
+3. **Maintainability** (los 3 sub-principios):
+   - ¿Un operario nuevo puede operarlo sin leer todo el código?
+   - ¿Un ingeniero nuevo puede entenderlo sin un curso?
+   - ¿Un cambio de requisito se acomoda sin reescribir?
+
+Si la respuesta es "no" a más de uno, el módulo necesita refactor antes de
+release.
+
+---
+
+## Parte 2 — Schema Evolution (Cap 4)
+
+Cita textual del libro (DDIA p.112, línea 5706-5719):
+
+> "Backward compatibility — Newer code can read data that was written by
+> older code.
+>
+> Forward compatibility — Older code can read data that was written by
+> newer code.
+>
+> Backward compatibility is normally not hard to achieve: as author of the
+> newer code, you know the format of data written by older code, and so
+> you can explicitly handle it (if necessary by simply keeping the old code
+> to read the old data). Forward compatibility can be trickier, because it
+> requires older code to ignore additions made by a newer version of the
+> code."
+
+### Las 2 direcciones de compatibilidad
+
+Cuando un schema evoluciona, hay dos preguntas distintas:
+
+| Pregunta | Tipo | Difficulty |
+|---|---|---|
+| ¿Código nuevo lee datos viejos? | Backward | Fácil |
+| ¿Código viejo lee datos nuevos? | Forward | Más difícil |
+
+**Backward compat es fácil**: el código nuevo conoce ambas versiones del
+schema, puede manejar los dos formatos.
+
+**Forward compat es difícil**: el código viejo NO sabe que existe el campo
+nuevo. Para que funcione, el código viejo debe **ignorar campos
+desconocidos** sin romperse.
+
+### Aplicación a schemas SWL
+
+SWL tiene 14 archivos `schemas/*.schema.json`. Reglas operativas:
+
+1. **Campos nuevos siempre opcionales**: agregar `myField: { type: "..." }`
+   sin marcarlo `required`. Código viejo lo ignora (forward-compat OK).
+   Código nuevo lo usa si está presente (backward-compat OK).
+
+2. **NUNCA renombrar campos en MINOR/PATCH**: rename = breaking. Si hay
+   que renombrar, mantener ambos durante 1 release (deprecación) y
+   eliminar en el MAJOR siguiente.
+
+3. **NUNCA cambiar tipo de un campo en MINOR/PATCH**: cambiar `string` →
+   `array` rompe ambas direcciones. Es MAJOR.
+
+4. **Agregar enum value es compatible**: si `nivelRiesgo` acepta
+   `[BAJO, MEDIO, ALTO]`, agregar `CRÍTICO` es backward-compat (código
+   nuevo lo entiende, código viejo lo rechaza pero no se rompe).
+
+5. **Eliminar enum value es breaking**: código nuevo rechaza algo que
+   código viejo escribía.
+
+### Detección de breaking changes
+
+Helper `scripts/lib/schema-version.js` (creado en F4) implementa estas
+reglas. Uso esperado:
+
+```js
+const { verificarCompatibilidad } = require('./scripts/lib/schema-version');
+const r = verificarCompatibilidad(documento, schema);
+// r = { compatible: bool, modo: "backward"|"forward"|"none", advertencias }
+```
+
+Tres modos según versiones:
+- Doc 1.0.0 + Schema 1.0.0 → `modo: "none"` (idénticas).
+- Doc 1.0.0 + Schema 1.1.0 → `modo: "forward"` (dato viejo, código nuevo).
+- Doc 1.1.0 + Schema 1.0.0 → `modo: "backward"` (dato nuevo, código viejo).
+- Doc 2.0.0 + Schema 1.0.0 → `compatible: false` (MAJOR rompe).
+
+---
+
+## Parte 3 — End-to-End Argument (Cap 12)
+
+Concepto del libro: la verificación de correctitud debe vivir en la
+frontera del sistema (end-to-end), no en cada capa intermedia.
+
+> "The End-to-End Argument for Databases" (DDIA p.516, sección referenciada)
+
+### El principio aplicado
+
+Si validas en cada capa intermedia:
+- Capa 1: valida → pasa
+- Capa 2: valida → pasa
+- Capa 3: valida → pasa
+- Resultado: dato corrupto entregado al usuario porque ninguna capa
+  verificó la **invariante de negocio** completa.
+
+Si validas end-to-end:
+- Capa 1, 2, 3: hacen su trabajo sin validar
+- Frontera del sistema: verifica la invariante completa
+- Resultado: si falla, se detecta antes de entregar al usuario.
+
+### Aplicación a SWL
+
+- `/swl:verificar` con goal-backward 4 niveles es end-to-end.
+- Hooks de validación intermedios (`calidad-pre-commit`,
+  `escaneo-secretos`) son fault-tolerance, no end-to-end. Detectan
+  problemas obvios temprano para reducir blast radius — no reemplazan la
+  verificación end-to-end.
+- Las dos capas son complementarias: hooks rápidos en cada step, verifier
+  end-to-end al cierre de fase.
+
+### Trust-but-Verify (Cap 12, p.528)
+
+El sistema debe **confiar provisionalmente** en sus componentes
+(hooks pasan → asumimos correcto) pero **verificar** la invariante final
+con evidencia, no con auto-reporte de los componentes.
+
+Aplicación SWL: regla `verificar-citas-normativas.md` aplica este
+principio a citas archivo:línea — un sub-agente reportó "está
+implementado en X:42"; el padre verifica con `Read`+`grep` antes de
+aceptar.
+
+---
+
+## Resumen — qué se llevó SWL del libro
+
+| Concepto DDIA | Dónde vive en SWL |
+|---|---|
+| Reliability/Scalability/Maintainability como framework | Este skill como rúbrica de evaluación |
+| Operability / Simplicity / Evolvability | Skills ≤300 líneas + observabilidad-swl + ADRs |
+| Backward / Forward compat | `$schemaVersion` + `scripts/lib/schema-version.js` (F4) |
+| End-to-End Argument | `/swl:verificar` goal-backward |
+| Trust-but-Verify | regla `verificar-citas-normativas.md` |
+
+## Origen
+
+Skill creado el 2026-05-18 como parte de Opción B de integración
+`temp/Designing Data Intensive Applications by Martin Kleppmann.md`. Ver
+ADR-0025 para la decisión de scope. Skill hermano:
+`proceso-ddia-streaming` (Cap 11 event sourcing aplicado a
+`evolucion/*.jsonl`).