@saulwade/swl-ses 1.6.0 → 1.6.3

package/habilidades/proceso-autoverificacion-evidencias/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: proceso-autoverificacion-evidencias
+description: >
+  Protocolo de auto-verificación post-implementación basado en las Four
+  Questions (tests passing / requirements met / assumptions verified /
+  evidence exists) + 7 red flags de alucinación. Cargar al cerrar una
+  feature, bugfix o refactor — antes de reportar "completado" al usuario,
+  antes del commit final, antes de mergear. Adaptación del SelfCheckProtocol
+  de SuperClaude_Framework, accuracy reportada 94% en detección de claims
+  no verificadas.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep, Glob, Bash]
+exclusiones:
+  - "No cargar para cambios triviales (typo, formato, comentario) — los checks no aportan valor."
+  - "No cargar en mitad de la implementación; este skill aplica al CIERRE. Para verificación pre-implementación usar `proceso-confianza-pre-implementacion`."
+  - "No cargar si ya se ejecutó `/swl:verificar` o el revisor de código emitió veredicto APROBADO — esos cubren el rol al nivel de fase/sesión."
+  - "No cargar para trabajo de research/discovery donde no hay implementación que cerrar."
+evolvable: true
+---
+
+# Habilidad: Auto-verificación con evidencias
+
+## Propósito
+
+Cerrar el trabajo con evidencias verificables, no con claims. El material
+fuente (SuperClaude_Framework `pm_agent/self_check.py`) reporta 94% de
+accuracy detectando los patrones de alucinación más comunes ("tests pass"
+sin mostrar output, "implementación completa" con tests rotos, lenguaje
+de incertidumbre). En SWL este patrón complementa la regla
+`verificar-citas-normativas.md` (que cubre citas durante el trabajo) con
+el protocolo de cierre obligatorio.
+
+## Cuándo cargar
+
+- Antes de reportar "completado" al usuario tras una implementación.
+- Antes del commit final de una feature/bugfix/refactor.
+- Antes de mergear un PR.
+- Cuando un sub-agente reporta éxito y el agente padre debe validar.
+- Cuando el usuario pregunta "¿está terminado?" y el agente está a punto
+  de responder "sí" — pasar por las Four Questions primero.
+
+## Cuándo NO cargar
+
+Listado en el campo `exclusiones` del frontmatter — incluye cambios
+triviales, mitad de implementación, casos donde `/swl:verificar` o el
+revisor ya emitió veredicto.
+
+---
+
+## Las Four Questions
+
+El protocolo es **mandatorio** — todas las cuatro preguntas se responden
+explícitamente. Si una se omite, el trabajo NO está cerrado.
+
+### Pregunta 1 — ¿Pasan todos los tests?
+
+No basta con afirmar "los tests pasan". Hay que **mostrar el output real**
+del runner.
+
+- Ejecutar el suite con el runner del proyecto (`npm test`, `pytest`,
+  `cargo test`, etc.).
+- Mostrar las últimas 20-50 líneas del output que incluyen el resumen
+  ("X passed, 0 failed").
+- Si hay tests skipped, indicar el conteo y la razón documentada.
+- Si los tests aún no se han escrito (TDD inverso, fix urgente), declararlo
+  explícitamente con plan de cierre.
+
+**Anti-patrón crítico**: "tests pasan" sin pegar el output. Es la red
+flag #1 de alucinación detectada por el patrón Reflexion.
+
+### Pregunta 2 — ¿Se cumplen todos los requisitos?
+
+Comparar requirements vs implementación, item por item:
+
+- Listar los requisitos originales del usuario o del plan.
+- Marcar cada uno: ✅ Hecho / ⚠️ Parcial / ❌ Pendiente.
+- Si hay parciales o pendientes: declarar por qué y cuándo se cierran.
+- No declarar "completo" si quedan ❌ no negociados.
+
+La regla `arreglar-al-detectar.md` prohíbe deuda silenciosa: si algo se
+deja para "después", se documenta como DA formal con trigger verificable,
+no como "lo dejo pendiente".
+
+### Pregunta 3 — ¿Hay suposiciones sin verificar?
+
+Toda suposición técnica usada durante la implementación debe estar
+verificada contra fuente autoritativa:
+
+- Suposiciones sobre APIs internas: verificadas leyendo el módulo, no por
+  nombre.
+- Suposiciones sobre librerías externas: verificadas en Context7 o doc
+  oficial (regla `usar-context7.md`).
+- Suposiciones sobre estructura del codebase: verificadas con `Grep`/`Glob`.
+- Suposiciones sobre comportamiento esperado del sistema: verificadas con
+  test o evidencia de ejecución.
+
+**Anti-patrón**: dejar "probablemente funciona", "debería andar", "creo
+que sí". Lenguaje de incertidumbre = red flag #7.
+
+### Pregunta 4 — ¿Hay evidencia?
+
+Evidencia concreta en tres ejes:
+
+- **Test results**: output del runner pegado (no resumen propio).
+- **Code changes**: lista de archivos modificados (`git diff --stat`).
+- **Validation**: lint, typecheck, build exitosos — output pegado.
+
+Si falta cualquiera de los tres, el trabajo NO está cerrado.
+
+---
+
+## Las 7 Red Flags de alucinación
+
+Patrones que indican que el agente está "cerrando sin verificar". Si el
+agente detecta cualquiera de estos en su propio output, debe corregir
+ANTES de reportar:
+
+1. **"Tests pass" sin output** — afirmación sin evidencia.
+2. **"Everything works" sin evidencia** — claim de completitud sin pruebas.
+3. **"Implementation complete" con tests rotos** — contradicción directa.
+4. **Saltar mensajes de error** — el runner reportó errores y el agente
+   los ignora en el reporte.
+5. **Ignorar warnings** — warnings tratados como ruido en lugar de señales
+   accionables.
+6. **Esconder fallos** — reportar éxitos parciales como totales.
+7. **Lenguaje de incertidumbre** — "probably", "should work", "might
+   work" en un reporte de cierre.
+
+Cada red flag detectada bloquea el cierre hasta que se resuelva.
+
+---
+
+## Formato de reporte obligatorio
+
+Al cerrar el trabajo, emitir al usuario (o registrar en
+`.planning/sessions/`) el siguiente formato:
+
+```
+### Auto-verificación de cierre
+
+**Pregunta 1 — Tests passing?**
+<output del runner pegado, últimas 20-50 líneas con resumen>
+Estado: ✅ N passed / ⚠️ M skipped con razón / ❌ K failed
+
+**Pregunta 2 — Requirements met?**
+- ✅ Requisito A: <evidencia / referencia a commit / archivo:línea>
+- ✅ Requisito B: <evidencia>
+- ⚠️ Requisito C: parcial — <qué falta y cuándo cierra>
+- ❌ Requisito D: pendiente — DA formal en `.planning/...` con trigger X
+
+**Pregunta 3 — Assumptions verified?**
+- ✅ Suposición X verificada en <fuente>
+- ✅ Suposición Y verificada con <comando/test>
+
+**Pregunta 4 — Evidence?**
+- Test results: <pegado arriba>
+- Code changes: `git diff --stat` →  <output>
+- Validation: lint/typecheck/build → <output o "no aplica al proyecto">
+
+**Red flags detectadas**: <lista o "ninguna">
+
+**Veredicto**: ✅ Cerrado con evidencias / ❌ Bloqueado por <razón>
+```
+
+Si el veredicto es ❌, el agente NO reporta "completado" al usuario.
+Reporta el bloqueo y propone el siguiente paso.
+
+---
+
+## Reglas obligatorias
+
+1. **Evidencia, no claims**: cualquier afirmación de éxito requiere output
+   pegado, no resumen propio. **Por qué**: el resumen propio puede ser
+   alucinado; el output real del runner no.
+
+2. **Las 4 preguntas son AND, no OR**: las cuatro deben pasar para cerrar.
+   No se puede compensar el fallo de una con el éxito de las otras.
+   **Por qué**: la regla `arreglar-al-detectar.md` exige resolver todo,
+   no esquivar; cerrar con 3 de 4 es deuda silenciosa.
+
+3. **Sin lenguaje de incertidumbre en el reporte**: las palabras
+   "probablemente", "creo que", "debería", "tal vez" están prohibidas en
+   el output de cierre. Si hay incertidumbre, verificarla; si no se puede
+   verificar, declararla explícitamente como gap con plan de cierre.
+
+4. **Re-leer el propio reporte**: antes de enviarlo, escanear las 7 red
+   flags. La detección es self-applied — si el agente no se audita, el
+   skill no funciona.
+
+5. **Si el cierre falla, NO ocultar**: reportar el fallo al usuario en
+   el mismo turno (regla `arreglar-al-detectar.md`). "Detecté que el
+   Check N falla porque X — voy a corregir Y" es la respuesta correcta.
+
+---
+
+## Relación con otras herramientas SWL
+
+- **Regla `verificar-citas-normativas.md`**: aplica DURANTE el trabajo a
+  cada cita verificable (archivo:línea, artículo de ley, etc.). Este
+  skill aplica al CIERRE del trabajo completo.
+- **Skill `proceso-confianza-pre-implementacion`**: aplica al INICIO con
+  las 5 dimensiones de confianza. Este aplica al CIERRE con las 4
+  preguntas. Forman par.
+- **Skill `verificar-trabajo`**: el agente Verificador SWL lo usa para
+  validación de fase con goal-backward 4 niveles. Si se ejecutó
+  `/swl:verificar` y aprobó, este skill no es necesario (cobertura
+  redundante).
+- **`revisor-codigo-swl`**: emite veredicto APROBADO/RECHAZADO sobre
+  código terminado. Si aprobó, este skill no es necesario.
+- **Skill `monitor-ci`** (regla global): aplica a CI post-push. Este
+  skill aplica antes del push.
+
+---
+
+## Ejemplo de uso
+
+Tras implementar el endpoint POST /facturas/cancelar:
+
+```
+### Auto-verificación de cierre
+
+**Pregunta 1 — Tests passing?**
+
+  PASS  tests/api/facturas-cancelar.test.ts
+  PASS  tests/services/factura-service.test.ts
+  Tests: 23 passed, 0 failed, 1 skipped
+  Time: 4.2 s
+
+Estado: ✅ 23 passed, 1 skipped (test de integración E2E pendiente de
+fixture de pago — no bloqueante, documentado en TODO.md).
+
+**Pregunta 2 — Requirements met?**
+- ✅ Endpoint POST /facturas/{id}/cancelar: implementado en
+  `backend/app/api/facturas.py:142`.
+- ✅ Validación de estatus permitido (solo "pendiente" o "emitida"):
+  implementada en `factura_service.py:88-101`.
+- ✅ Auditoría: registro en tabla `factura_historial`: confirmado en
+  test `factura-cancelar-audit.test.py:55`.
+
+**Pregunta 3 — Assumptions verified?**
+- ✅ Modelo Factura tiene método `puede_cancelarse()`: confirmado leyendo
+  `models/factura.py:120-135`.
+- ✅ FastAPI `Depends(get_db)` es la inyección estándar del proyecto:
+  confirmado en ADR-0008 y 12 endpoints existentes.
+
+**Pregunta 4 — Evidence?**
+- Test results: pegado arriba.
+- Code changes:
+  3 files changed, 84 insertions(+), 2 deletions(-)
+  backend/app/api/facturas.py | 32 ++++++++++++++++++--
+  backend/app/services/factura_service.py | 18 +++++++++++
+  backend/tests/api/facturas-cancelar.test.ts | 36 +++++++++++++++++++
+- Validation: `ruff check .` → 0 errors, `mypy backend/` → 0 errors.
+
+**Red flags detectadas**: ninguna.
+
+**Veredicto**: ✅ Cerrado con evidencias.
+```

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.