@saulwade/swl-ses 2.5.3 → 2.6.1

package/habilidades/prevencion-sobreingenieria/recursos/variables-residuales-post-refactor.md

@@ -1,85 +1,85 @@
-# Variables residuales post-refactor son code smell
-
-Recurso de `prevencion-sobreingenieria`. Extraído del SKILL.md en v1.3.0 para
-respetar el límite de 300 líneas; el contenido es normativo sin cambios.
-
-## Regla
-
-Variables asignadas pero no usadas (F841 en ruff/flake8) **post-refactor** son
-casi siempre residuos de una versión anterior del código que el refactor no
-limpió. Se parecen a "variables temporales del desarrollador" pero delatan un
-refactor incompleto — la lógica que las usaba se movió o eliminó, pero las
-asignaciones quedaron.
-
-## Por qué son peligrosas
-
-- **Confunden al próximo lector**: asumirá que la variable se usa más abajo.
-- **Inflan el diff cognitivo** del refactor real.
-- **Ocultan bugs sutiles**: el valor asignado puede tener side effects (llamada
-  a función costosa o con efecto en estado) que ya no aporta nada al flujo.
-- **Invalidan la métrica de cobertura**: líneas "cubiertas" por tests que en
-  realidad no afectan el resultado.
-
-## Patrón operativo
-
-Después de **cualquier refactor** que modifique el flujo de una función (extraer
-método, inlinear función, cambiar el shape de un return), correr:
-
-```bash
-ruff check --select=F841 ruta/al/modulo.py
-# o para todo el proyecto
-ruff check --select=F841 .
-```
-
-Cada F841 detectado post-refactor es candidato 1 de 2:
-
-1. **Variable muerta** (caso común post-refactor): eliminarla.
-2. **Variable viva pero mal nombrada** (caso raro): si el valor se usa como
-   side effect intencional (ej: evaluar una propiedad para cachear), renombrar
-   con prefijo `_` y comentar el propósito.
-
-## Anti-patrón típico
-
-```python
-# Antes del refactor: había un if que usaba exito_key
-def procesar(data):
-    exito, exito_key = intentar(data)
-    if exito_key == "via_rapida":
-        return procesar_rapido(data)
-    return procesar_normal(data, exito_key)
-
-
-# Después de refactor que eliminó la rama "via_rapida"
-def procesar(data):
-    exito, exito_key = intentar(data)   # ← F841: exito_key asignado, no usado
-    return procesar_normal(data)         # ← también exito residual
-```
-
-## Patrón canónico
-
-```python
-# Post-refactor limpio
-def procesar(data):
-    _ = intentar(data)   # si el side effect de intentar() importa
-    return procesar_normal(data)
-
-# o mejor: si ni siquiera el side effect importa
-def procesar(data):
-    return procesar_normal(data)
-```
-
-## Reglas
-
-- **Gate pre-commit**: agregar `ruff check --select=F841` al pre-commit hook del proyecto. No bloquea en un repo grande donde F841 preexiste, pero sí bloquea en los archivos modificados por el commit actual.
-- **Revisión explícita post-refactor grande**: tras extraer 5+ métodos o mover 5+ bloques, correr `ruff --select=F401,F841` sobre los archivos tocados.
-- **NO silenciar con `# noqa: F841` sin justificación** — la excepción legítima (side effect intencional con nombre `_`) es tan rara que vale la pena documentarla; silenciar sin comentario es ocultar deuda.
-- **Incluir en checklist de PR**: "F841 limpio en archivos tocados" como item explícito.
-
-## Aplicabilidad
-
-Detectable en:
-
-- Python: `ruff --select=F841`, `flake8 --select=F841`.
-- TypeScript/JavaScript: `eslint --rule 'no-unused-vars: error'`.
-- Go: el compilador lo hace obligatorio (`declared but not used`).
-- Rust: warning `unused_variables`, promovido a error con `#![deny(unused_variables)]`.
+# Variables residuales post-refactor son code smell
+
+Recurso de `prevencion-sobreingenieria`. Extraído del SKILL.md en v1.3.0 para
+respetar el límite de 300 líneas; el contenido es normativo sin cambios.
+
+## Regla
+
+Variables asignadas pero no usadas (F841 en ruff/flake8) **post-refactor** son
+casi siempre residuos de una versión anterior del código que el refactor no
+limpió. Se parecen a "variables temporales del desarrollador" pero delatan un
+refactor incompleto — la lógica que las usaba se movió o eliminó, pero las
+asignaciones quedaron.
+
+## Por qué son peligrosas
+
+- **Confunden al próximo lector**: asumirá que la variable se usa más abajo.
+- **Inflan el diff cognitivo** del refactor real.
+- **Ocultan bugs sutiles**: el valor asignado puede tener side effects (llamada
+  a función costosa o con efecto en estado) que ya no aporta nada al flujo.
+- **Invalidan la métrica de cobertura**: líneas "cubiertas" por tests que en
+  realidad no afectan el resultado.
+
+## Patrón operativo
+
+Después de **cualquier refactor** que modifique el flujo de una función (extraer
+método, inlinear función, cambiar el shape de un return), correr:
+
+```bash
+ruff check --select=F841 ruta/al/modulo.py
+# o para todo el proyecto
+ruff check --select=F841 .
+```
+
+Cada F841 detectado post-refactor es candidato 1 de 2:
+
+1. **Variable muerta** (caso común post-refactor): eliminarla.
+2. **Variable viva pero mal nombrada** (caso raro): si el valor se usa como
+   side effect intencional (ej: evaluar una propiedad para cachear), renombrar
+   con prefijo `_` y comentar el propósito.
+
+## Anti-patrón típico
+
+```python
+# Antes del refactor: había un if que usaba exito_key
+def procesar(data):
+    exito, exito_key = intentar(data)
+    if exito_key == "via_rapida":
+        return procesar_rapido(data)
+    return procesar_normal(data, exito_key)
+
+
+# Después de refactor que eliminó la rama "via_rapida"
+def procesar(data):
+    exito, exito_key = intentar(data)   # ← F841: exito_key asignado, no usado
+    return procesar_normal(data)         # ← también exito residual
+```
+
+## Patrón canónico
+
+```python
+# Post-refactor limpio
+def procesar(data):
+    _ = intentar(data)   # si el side effect de intentar() importa
+    return procesar_normal(data)
+
+# o mejor: si ni siquiera el side effect importa
+def procesar(data):
+    return procesar_normal(data)
+```
+
+## Reglas
+
+- **Gate pre-commit**: agregar `ruff check --select=F841` al pre-commit hook del proyecto. No bloquea en un repo grande donde F841 preexiste, pero sí bloquea en los archivos modificados por el commit actual.
+- **Revisión explícita post-refactor grande**: tras extraer 5+ métodos o mover 5+ bloques, correr `ruff --select=F401,F841` sobre los archivos tocados.
+- **NO silenciar con `# noqa: F841` sin justificación** — la excepción legítima (side effect intencional con nombre `_`) es tan rara que vale la pena documentarla; silenciar sin comentario es ocultar deuda.
+- **Incluir en checklist de PR**: "F841 limpio en archivos tocados" como item explícito.
+
+## Aplicabilidad
+
+Detectable en:
+
+- Python: `ruff --select=F841`, `flake8 --select=F841`.
+- TypeScript/JavaScript: `eslint --rule 'no-unused-vars: error'`.
+- Go: el compilador lo hace obligatorio (`declared but not used`).
+- Rust: warning `unused_variables`, promovido a error con `#![deny(unused_variables)]`.

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

@@ -175,8 +175,9 @@ SWL tiene 14 archivos `schemas/*.schema.json`. Reglas operativas:
 
 ### Detección de breaking changes
 
-Helper `scripts/lib/schema-version.js` (creado en F4) implementa estas
-reglas. Uso esperado:
+Helper `scripts/lib/schema-version.js` (creado en F4, layout del repo madre;
+en instalaciones destino vive aplanado junto a los hooks) implementa estas
+reglas. Referencia de API — uso esperado:
 
 ```js
 const { verificarCompatibilidad } = require('./scripts/lib/schema-version');

package/habilidades/proceso-ingenieria-requerimientos/SKILL.md

@@ -1,147 +1,147 @@
----
-name: proceso-ingenieria-requerimientos
-description: >
-  Checklist de calidad de requerimientos basado en ingeniería de
-  requerimientos clásica (investigación académica del autor, 2003; refs
-  ZAVE94 y RE'01): las 8 características del buen requerimiento (correcto,
-  necesario, conciso, libre de implementación, factible, priorizable, no
-  ambiguo, verificable), la heurística "una verificación = un requerimiento",
-  la metadata de soporte por REQ (IDUR, padre, fuente, razón, riesgo, estado)
-  y la jerarquía de verificación (inspección < demostración < prueba).
-  Cargar al congelar REQs en /swl:discutir-fase (Bloque 5), al redactar
-  criterios de aceptación en un PRD (producto-prd-swl), o al auditar la
-  calidad de un CONTEXTO.md/REQUISITOS.md existente.
-version: "1.0.0"
-herramientasPermitidas: [Read]
-evolvable: true
-exclusiones:
-  - "No cargar para descomponer REQs en tareas — eso es planificador-swl con el REQ ya congelado."
-  - "No cargar para verificar la CADENA REQ→tarea→commit→test — eso es el gate G4 de /swl:verificar; este skill mejora la calidad del REQ ANTES de que exista la cadena."
-  - "No cargar para decisiones de arquitectura — un ADR documenta el CÓMO se decide; este skill vigila que el REQ diga el QUÉ sin contaminarse de cómo."
----
-# Ingeniería de requerimientos — checklist de calidad por REQ
-
-Un requerimiento mal escrito se propaga: el plan lo descompone mal, el test
-lo verifica mal y el gate G4 valida una cadena correcta sobre un contenido
-incorrecto. Este skill se aplica a **cada REQ individual antes de congelarlo**
-(cierre de `discutir-fase`, redacción de PRD), no a la cadena posterior.
-
-> La IR "funciona como el puente entre la necesidad que tienen los usuarios
-> del mundo real [...] y las capacidades y oportunidades que brinda la
-> tecnología" (RE'01). El REQ es ese puente: si el puente está torcido, todo
-> lo que cruza llega torcido.
-
-## Cuándo cargar
-
-- Al cerrar el **Bloque 5** de `discutir-fase` (criterios de aceptación),
-  antes de escribir los `REQ-<fase>-NN` al CONTEXTO.md.
-- Al redactar criterios de aceptación e historias en un PRD.
-- Al auditar un CONTEXTO.md o REQUISITOS.md existente (¿por qué esta fase
-  divergió? — a menudo el REQ era ambiguo desde el origen).
-
-## Las 8 características — checklist con prueba operativa
-
-Aplicar a CADA requerimiento. Un REQ que falla una característica se
-reescribe antes de congelar, no después de implementar.
-
-| # | Característica | Prueba operativa |
-|---|---|---|
-| 1 | **Correcto** | Solo el usuario (o su sustituto cercano) determina si es correcto — validarlo con él en la entrevista. "Probablemente es lo que querían" = adivinar, no elicitar. |
-| 2 | **Necesario** | Rastrear a una fuente con autoridad (petición del usuario, REQ padre, estándar, regulación). Prueba: *¿si lo elimino, qué necesidad queda sin resolver?* Sin respuesta = *gold plating* — fuera. |
-| 3 | **Conciso** | Dice QUÉ debe hacerse y solo eso. Explicaciones, racional y análisis van en la metadata `Razón`, no en el enunciado. |
-| 4 | **Libre de implementación** | Dice qué, no cómo. Regla de cascada: *"el diseño de un nivel es el requerimiento del nivel inferior"* — la solución elegida (ADR) genera los REQs del siguiente nivel, sin fijar el diseño de ese nivel. Excepción legítima: requerimientos de interface. |
-| 5 | **Factible** | Chequeo de realidad técnica y de costo contra el sistema y su ambiente conocidos. Valores numéricos sospechosos se retan con física/límites del stack (el radar no ve más allá del horizonte). `/swl:predecir --abogado-diablo` es el retador formal. |
-| 6 | **Priorizable** | Prioridad asignada = f(valor al cliente, costo relativo, riesgo técnico). Si todo es igual de importante, no se puede reaccionar a recortes ni imprevistos. |
-| 7 | **No ambiguo** | Todos los lectores llegan a UNA interpretación. Palabras prohibidas en el enunciado: *fácil, simple, rápido, eficiente, varios, mejorado, robusto, flexible, amigable, maximizar, minimizar, soportar*. Cada una se reemplaza por un valor medible o se elimina. |
-| 8 | **Verificable** | Enunciado en términos mensurables con tolerancias ("105 ± 0.5", "p95 < N ms", "0 hallazgos CRÍTICOS"). Un REQ no verificable convierte la aceptación en cuestión de opinión. No consistente/no factible/ambiguo ⇒ no verificable. |
-
-## Heurística de concisión: una verificación = un requerimiento
-
-¿La alarma visual y la audible son uno o dos REQs? **Se decide por cómo se
-verificará**: si una sola prueba/demostración las verifica juntas, son UN
-requerimiento; si exigen verificaciones separadas, son DOS. Ni párrafos con
-múltiples REQs escondidos, ni multiplicar REQs sin razón — cada REQ se
-administra y verifica, y eso cuesta.
-
-## Tipos técnicos (y su relación de verificación)
-
-- **Funcional** — cualitativo: qué hace ("detectar blancos"). Se verifica por
-  la SUMA de sus requerimientos de desempeño asociados.
-- **Desempeño** — cuantitativo y comprobable individualmente ("detectar 0.1 m²
-  a >20 km con Pd ≥ 0.9"). Usualmente varios por cada funcional.
-- **Restricción de diseño** — límites bajo los que debe existir (peso, tamaño,
-  ambiente, stack impuesto).
-- **Interface** — cómo interactúa con sistemas externos o entre subsistemas;
-  la excepción documentada a "libre de implementación".
-
-## Metadata de soporte por REQ
-
-El REQ es un objeto de primera clase con metadata, no una línea suelta:
-
-| Atributo | En swl-ses | Regla |
-|---|---|---|
-| **IDUR** | `REQ-<fase>-NN` (namespaceado) | Único, jamás reutilizado |
-| **Padre** | `padre: REQ-<fase>-MM` (opcional) | Para REQs derivados de uno de nivel superior — da trazabilidad vertical |
-| **Fuente** | quién/qué lo pidió (usuario en entrevista, PRD §, estándar, regla) | Sin fuente identificable → aplica prueba de "necesario" |
-| **Razón** | 1 línea de racional o puntero (análisis, ADR, supuesto del Bloque 4) | Aquí vive lo que "conciso" echó del enunciado |
-| **Riesgo** | alto/medio/bajo + por qué | Alimenta la priorización del plan |
-| **Estado** | `PENDIENTE → definido → aprobado (gate G1) → verificado (gate G4) → borrado` | Mapa del ciclo PSD/PSR/Definido/Aprobado/Verificado/Borrado clásico; REQs `PENDIENTE` bloquean el cierre de la discusión |
-
-## Jerarquía de verificación (al declarar CÓMO se verificará cada REQ)
-
-**Inspección** (mirar/medir el artefacto) < **demostración** (observar la
-operación con instrumentación mínima — p. ej. medir MTTR reparando fallas
-inducidas) < **prueba** (instrumentada por completo — la más confiable y la
-más cara) — con **análisis** como soporte barato (modelos validados contra
-pruebas previas). Elegir el método MÁS BARATO que realmente verifique el
-REQ; declarar el método junto al criterio de aceptación.
-
-## Dos escalas de priorización (usar una, explícita)
-
-- **Alto / Medio / Bajo** — crítico de misión para la próxima liberación /
-  necesario eventualmente / mejora si los recursos lo permiten.
-- **Esencial / Condicional / Opcional** — el producto no es aceptable sin él /
-  mejora pero el producto es aceptable sin ella / puede o no valer la pena.
-- MoSCoW (del PRD) mapea: Must≈Esencial, Should/Could≈Condicional,
-  Won't≈fuera. Declarar QUÉ escala se usa; nunca mezclar dos en el mismo doc.
-
-## Por qué la elicitación falla (y qué hace el cuestionario al respecto)
-
-Restricciones clásicas que el entrevistador debe asumir como default:
-**conocimiento tácito** (la gente no sabe describir lo que hace — pedir
-ejemplos concretos, no definiciones), **distribución del conocimiento**
-(fuentes múltiples en conflicto — los conflictos se registran como decisiones
-del Bloque 4, no se resuelven en silencio), **observación limitada** y
-**parcialidad** (el resultado afecta al informante). Es la razón por la que
-`discutir-fase` pregunta supuestos explícitos y registra decisiones con
-estado en vez de asumir consenso.
-
-## Cuándo NO cargar
-
-- REQs ya congelados con plan aprobado (gate G1) — re-litigar el REQ ahí es
-  cambio de scope: pasa por re-planificación, no por este checklist.
-- Tareas técnicas triviales sin REQs formales (fix puntual, typo).
-- Verificación post-implementación — eso es `/swl:verificar` (G4).
-
-## Gotchas / Errores comunes no obvios
-
-- **Checklist aplicado al documento y no al requerimiento**: las 8
-  características se evalúan POR REQ individual; un CONTEXTO.md "en general
-  claro" puede contener 2 REQs ambiguos que revientan la fase.
-- **"Verificable" confundido con "tiene test"**: verificable es una propiedad
-  del ENUNCIADO (términos mensurables), previa al test. G4 valida que el test
-  exista; este skill valida que el enunciado sea testeable.
-- **Racional dentro del enunciado**: si el REQ explica por qué, mezcla dos
-  atributos — mover el porqué a `Razón` y dejar el enunciado conciso.
-- **Funcional "verificado" directamente**: un funcional sin desempeños
-  asociados se "verifica" con opinión. Todo funcional no trivial necesita al
-  menos un desempeño cuantitativo asociado.
-
----
-
-**Origen**: investigación académica de Saúl Wade, *"Ingeniería de
-requerimientos"* (Wade Inc., ~2003; referencias [ZAVE94] y [RE'01 CfP]),
-absorbida al sistema el 2026-07-08 (v2.5.1). El documento fuente vive en
-`temp/` del repo madre (material de referencia, no distribuido); este skill
-es su destilado operativo con el mapeo a los mecanismos SWL (gates G1/G4,
-cuestionario de discutir-fase, MoSCoW del PRD).
+---
+name: proceso-ingenieria-requerimientos
+description: >
+  Checklist de calidad de requerimientos basado en ingeniería de
+  requerimientos clásica (investigación académica del autor, 2003; refs
+  ZAVE94 y RE'01): las 8 características del buen requerimiento (correcto,
+  necesario, conciso, libre de implementación, factible, priorizable, no
+  ambiguo, verificable), la heurística "una verificación = un requerimiento",
+  la metadata de soporte por REQ (IDUR, padre, fuente, razón, riesgo, estado)
+  y la jerarquía de verificación (inspección < demostración < prueba).
+  Cargar al congelar REQs en /swl:discutir-fase (Bloque 5), al redactar
+  criterios de aceptación en un PRD (producto-prd-swl), o al auditar la
+  calidad de un CONTEXTO.md/REQUISITOS.md existente.
+version: "1.0.0"
+herramientasPermitidas: [Read]
+evolvable: true
+exclusiones:
+  - "No cargar para descomponer REQs en tareas — eso es planificador-swl con el REQ ya congelado."
+  - "No cargar para verificar la CADENA REQ→tarea→commit→test — eso es el gate G4 de /swl:verificar; este skill mejora la calidad del REQ ANTES de que exista la cadena."
+  - "No cargar para decisiones de arquitectura — un ADR documenta el CÓMO se decide; este skill vigila que el REQ diga el QUÉ sin contaminarse de cómo."
+---
+# Ingeniería de requerimientos — checklist de calidad por REQ
+
+Un requerimiento mal escrito se propaga: el plan lo descompone mal, el test
+lo verifica mal y el gate G4 valida una cadena correcta sobre un contenido
+incorrecto. Este skill se aplica a **cada REQ individual antes de congelarlo**
+(cierre de `discutir-fase`, redacción de PRD), no a la cadena posterior.
+
+> La IR "funciona como el puente entre la necesidad que tienen los usuarios
+> del mundo real [...] y las capacidades y oportunidades que brinda la
+> tecnología" (RE'01). El REQ es ese puente: si el puente está torcido, todo
+> lo que cruza llega torcido.
+
+## Cuándo cargar
+
+- Al cerrar el **Bloque 5** de `discutir-fase` (criterios de aceptación),
+  antes de escribir los `REQ-<fase>-NN` al CONTEXTO.md.
+- Al redactar criterios de aceptación e historias en un PRD.
+- Al auditar un CONTEXTO.md o REQUISITOS.md existente (¿por qué esta fase
+  divergió? — a menudo el REQ era ambiguo desde el origen).
+
+## Las 8 características — checklist con prueba operativa
+
+Aplicar a CADA requerimiento. Un REQ que falla una característica se
+reescribe antes de congelar, no después de implementar.
+
+| # | Característica | Prueba operativa |
+|---|---|---|
+| 1 | **Correcto** | Solo el usuario (o su sustituto cercano) determina si es correcto — validarlo con él en la entrevista. "Probablemente es lo que querían" = adivinar, no elicitar. |
+| 2 | **Necesario** | Rastrear a una fuente con autoridad (petición del usuario, REQ padre, estándar, regulación). Prueba: *¿si lo elimino, qué necesidad queda sin resolver?* Sin respuesta = *gold plating* — fuera. |
+| 3 | **Conciso** | Dice QUÉ debe hacerse y solo eso. Explicaciones, racional y análisis van en la metadata `Razón`, no en el enunciado. |
+| 4 | **Libre de implementación** | Dice qué, no cómo. Regla de cascada: *"el diseño de un nivel es el requerimiento del nivel inferior"* — la solución elegida (ADR) genera los REQs del siguiente nivel, sin fijar el diseño de ese nivel. Excepción legítima: requerimientos de interface. |
+| 5 | **Factible** | Chequeo de realidad técnica y de costo contra el sistema y su ambiente conocidos. Valores numéricos sospechosos se retan con física/límites del stack (el radar no ve más allá del horizonte). `/swl:predecir --abogado-diablo` es el retador formal. |
+| 6 | **Priorizable** | Prioridad asignada = f(valor al cliente, costo relativo, riesgo técnico). Si todo es igual de importante, no se puede reaccionar a recortes ni imprevistos. |
+| 7 | **No ambiguo** | Todos los lectores llegan a UNA interpretación. Palabras prohibidas en el enunciado: *fácil, simple, rápido, eficiente, varios, mejorado, robusto, flexible, amigable, maximizar, minimizar, soportar*. Cada una se reemplaza por un valor medible o se elimina. |
+| 8 | **Verificable** | Enunciado en términos mensurables con tolerancias ("105 ± 0.5", "p95 < N ms", "0 hallazgos CRÍTICOS"). Un REQ no verificable convierte la aceptación en cuestión de opinión. No consistente/no factible/ambiguo ⇒ no verificable. |
+
+## Heurística de concisión: una verificación = un requerimiento
+
+¿La alarma visual y la audible son uno o dos REQs? **Se decide por cómo se
+verificará**: si una sola prueba/demostración las verifica juntas, son UN
+requerimiento; si exigen verificaciones separadas, son DOS. Ni párrafos con
+múltiples REQs escondidos, ni multiplicar REQs sin razón — cada REQ se
+administra y verifica, y eso cuesta.
+
+## Tipos técnicos (y su relación de verificación)
+
+- **Funcional** — cualitativo: qué hace ("detectar blancos"). Se verifica por
+  la SUMA de sus requerimientos de desempeño asociados.
+- **Desempeño** — cuantitativo y comprobable individualmente ("detectar 0.1 m²
+  a >20 km con Pd ≥ 0.9"). Usualmente varios por cada funcional.
+- **Restricción de diseño** — límites bajo los que debe existir (peso, tamaño,
+  ambiente, stack impuesto).
+- **Interface** — cómo interactúa con sistemas externos o entre subsistemas;
+  la excepción documentada a "libre de implementación".
+
+## Metadata de soporte por REQ
+
+El REQ es un objeto de primera clase con metadata, no una línea suelta:
+
+| Atributo | En swl-ses | Regla |
+|---|---|---|
+| **IDUR** | `REQ-<fase>-NN` (namespaceado) | Único, jamás reutilizado |
+| **Padre** | `padre: REQ-<fase>-MM` (opcional) | Para REQs derivados de uno de nivel superior — da trazabilidad vertical |
+| **Fuente** | quién/qué lo pidió (usuario en entrevista, PRD §, estándar, regla) | Sin fuente identificable → aplica prueba de "necesario" |
+| **Razón** | 1 línea de racional o puntero (análisis, ADR, supuesto del Bloque 4) | Aquí vive lo que "conciso" echó del enunciado |
+| **Riesgo** | alto/medio/bajo + por qué | Alimenta la priorización del plan |
+| **Estado** | `PENDIENTE → definido → aprobado (gate G1) → verificado (gate G4) → borrado` | Mapa del ciclo PSD/PSR/Definido/Aprobado/Verificado/Borrado clásico; REQs `PENDIENTE` bloquean el cierre de la discusión |
+
+## Jerarquía de verificación (al declarar CÓMO se verificará cada REQ)
+
+**Inspección** (mirar/medir el artefacto) < **demostración** (observar la
+operación con instrumentación mínima — p. ej. medir MTTR reparando fallas
+inducidas) < **prueba** (instrumentada por completo — la más confiable y la
+más cara) — con **análisis** como soporte barato (modelos validados contra
+pruebas previas). Elegir el método MÁS BARATO que realmente verifique el
+REQ; declarar el método junto al criterio de aceptación.
+
+## Dos escalas de priorización (usar una, explícita)
+
+- **Alto / Medio / Bajo** — crítico de misión para la próxima liberación /
+  necesario eventualmente / mejora si los recursos lo permiten.
+- **Esencial / Condicional / Opcional** — el producto no es aceptable sin él /
+  mejora pero el producto es aceptable sin ella / puede o no valer la pena.
+- MoSCoW (del PRD) mapea: Must≈Esencial, Should/Could≈Condicional,
+  Won't≈fuera. Declarar QUÉ escala se usa; nunca mezclar dos en el mismo doc.
+
+## Por qué la elicitación falla (y qué hace el cuestionario al respecto)
+
+Restricciones clásicas que el entrevistador debe asumir como default:
+**conocimiento tácito** (la gente no sabe describir lo que hace — pedir
+ejemplos concretos, no definiciones), **distribución del conocimiento**
+(fuentes múltiples en conflicto — los conflictos se registran como decisiones
+del Bloque 4, no se resuelven en silencio), **observación limitada** y
+**parcialidad** (el resultado afecta al informante). Es la razón por la que
+`discutir-fase` pregunta supuestos explícitos y registra decisiones con
+estado en vez de asumir consenso.
+
+## Cuándo NO cargar
+
+- REQs ya congelados con plan aprobado (gate G1) — re-litigar el REQ ahí es
+  cambio de scope: pasa por re-planificación, no por este checklist.
+- Tareas técnicas triviales sin REQs formales (fix puntual, typo).
+- Verificación post-implementación — eso es `/swl:verificar` (G4).
+
+## Gotchas / Errores comunes no obvios
+
+- **Checklist aplicado al documento y no al requerimiento**: las 8
+  características se evalúan POR REQ individual; un CONTEXTO.md "en general
+  claro" puede contener 2 REQs ambiguos que revientan la fase.
+- **"Verificable" confundido con "tiene test"**: verificable es una propiedad
+  del ENUNCIADO (términos mensurables), previa al test. G4 valida que el test
+  exista; este skill valida que el enunciado sea testeable.
+- **Racional dentro del enunciado**: si el REQ explica por qué, mezcla dos
+  atributos — mover el porqué a `Razón` y dejar el enunciado conciso.
+- **Funcional "verificado" directamente**: un funcional sin desempeños
+  asociados se "verifica" con opinión. Todo funcional no trivial necesita al
+  menos un desempeño cuantitativo asociado.
+
+---
+
+**Origen**: investigación académica de Saúl Wade, *"Ingeniería de
+requerimientos"* (Wade Inc., ~2003; referencias [ZAVE94] y [RE'01 CfP]),
+absorbida al sistema el 2026-07-08 (v2.5.1). El documento fuente vive en
+`temp/` del repo madre (material de referencia, no distribuido); este skill
+es su destilado operativo con el mapeo a los mecanismos SWL (gates G1/G4,
+cuestionario de discutir-fase, MoSCoW del PRD).

package/habilidades/release-semver/SKILL.md

@@ -318,8 +318,8 @@ de token inválido.
 - `semantic-release` ya está configurado en CI — si el release está automatizado, el número de versión se calcula desde los commits sin intervención manual; cargar este skill duplicaría el trabajo.
 - El proyecto es una herramienta interna sin consumidores que dependan de compatibilidad de versión — SemVer completo compensa cuando hay consumidores que confían en los números de versión para evaluar breaking changes.
 
-## Gotchas / Errores comunes no obvios
-
+## Gotchas / Errores comunes no obvios
+
 - **El registry espejo NUNCA publica cuando el canónico falló sus gates** [caso real: v2.5.0 y v2.5.1 quedaron huérfanas en GitHub Packages, 2026-07-08/09]: un publisher dual que publica el mirror desde un directorio temporal preparado (donde `prepublishOnly`/gates NO corren) debe condicionar el paso 2 al éxito del paso 1 — si el canónico falló, el mirror se OMITE con aviso visible. Publicar tras el fallo sube un tarball sin validar y desalinea los registries: la misma versión no puede re-subirse, forzando un "republish de coordinación" (bump PATCH) que es puro costo. Verificar además que el flujo del mirror realmente corre gates en alguna parte — "los pre-publish ya pasaron en el intento 1" es una suposición, no una garantía.
 
 - **Tag ligero creado en lugar de anotado para el release**: `git tag v2.1.0` sin la flag `-a` crea un tag ligero que no incluye metadata de autor, fecha ni mensaje. Causa: olvidar la flag `-a` o la costumbre de usar tags ligeros para marcado temporal. Solución: siempre `git tag -a v2.1.0 -m "Release v2.1.0"` para releases — los tags anotados son los que `git describe` y las herramientas de changelog usan correctamente.

package/habilidades/swl-claudemd/SKILL.md

@@ -53,13 +53,12 @@ Más dos prácticas auxiliares del video:
 Ejecuta el auditor determinista:
 
 ```bash
-# Repo de swl-ses (script local): node scripts/auditar-claudemd.js [--json|--strict]
-# Proyecto downstream (NO existe el script local): usar el subcomando del CLI:
-npx -y @saulwade/swl-ses@latest audit-claudemd [--json|--strict]
+# CLI cross-scope: en el repo madre resuelve al script local, en proyectos
+# downstream al paquete instalado/npx. Mismo auditor en ambos casos.
+swl-ses audit-claudemd [--json|--strict]
 ```
 
-Regla: si `scripts/auditar-claudemd.js` no existe en el CWD, usar SIEMPRE
-`npx ... audit-claudemd` — ambas rutas ejecutan el mismo auditor.
+Si `swl-ses` no está en PATH: `npx -y @saulwade/swl-ses@latest audit-claudemd`.
 
 El auditor verifica nueve dimensiones (la fila `@references rotos` caza el `@reglas/...` roto downstream):
 
@@ -205,8 +204,8 @@ y mensaje WARN — project-level >50 LOC sin mención a los 4 principios).
 `/swl:aprender` **muta** CLAUDE.md; `/swl:claudemd` **prescribe contrato**.
 Todo comando SWL que escriba a CLAUDE.md del proyecto (`aprender`,
 `adoptar-proyecto`, `nuevo-proyecto`, `claudemd init-project`, futuros) DEBE
-ejecutar el auditor síncrono tras escribir (`node scripts/auditar-claudemd.js
---json`), evaluar el veredicto (OK→continuar; WARN→proponer condensar/extraer;
+ejecutar el auditor síncrono tras escribir (`swl-ses audit-claudemd --json`,
+CLI cross-scope), evaluar el veredicto (OK→continuar; WARN→proponer condensar/extraer;
 `ERROR placeholders`→**DETENER y revertir**) y re-auditar hasta OK/WARN aceptable.
 
 Doble red: capa síncrona (Paso 6.5 de aprender — proactiva, bloquea el comando)

package/habilidades/swl-dashboard/SKILL.md

@@ -243,51 +243,15 @@ Muestra en terminal las métricas de activación y bloqueo de los guardrails (ho
 de la sesión actual. Los datos provienen de `hooks/lib/guardrail-metrics.js`.
 
 ```bash
-# Leer métricas de guardrails de la sesión actual desde /tmp/
-SESSION_ID="${CLAUDE_SESSION_ID:-default}"
-BRIDGE_FILE="/tmp/swl-guardrail-metrics-${SESSION_ID}.json"
-
-if [ -f "$BRIDGE_FILE" ]; then
-  node -e "
-    const m = require('$BRIDGE_FILE');
-    const hooks = m.hooks || {};
-    const entries = Object.entries(hooks).sort(([,a],[,b]) => b.bloqueos - a.bloqueos);
-    if (entries.length === 0) {
-      console.log('Ningún guardrail se activó en esta sesión.');
-    } else {
-      console.log('\\nGuardrails — Activaciones de la sesión\\n');
-      console.log('Hook'.padEnd(30) + 'Activaciones'.padStart(13) + 'Bloqueos'.padStart(9) + 'Warnings'.padStart(9) + 'Tasa'.padStart(7));
-      console.log('-'.repeat(68));
-      for (const [nombre, datos] of entries) {
-        const tasa = datos.activaciones > 0 ? Math.round(datos.bloqueos / datos.activaciones * 100) + '%' : '0%';
-        console.log(nombre.replace('.js','').padEnd(30) + String(datos.activaciones).padStart(13) + String(datos.bloqueos).padStart(9) + String(datos.warnings).padStart(9) + tasa.padStart(7));
-      }
-    }
-  "
-else
-  echo "Sin datos de guardrails para esta sesión. (bridge: $BRIDGE_FILE)"
-  echo "Los guardrails registran métricas cuando se activan durante la sesión."
-fi
+# Tabla de activaciones + diagnóstico automático de la sesión actual
+# (--session=ID para otra sesión; --json para salida cruda)
+swl-ses guardrail-metrics
 ```
 
-Después de mostrar la tabla, ejecutar diagnóstico automático:
-
-```bash
-node -e "
-  try {
-    const { getMetrics, diagnosticar } = require('./hooks/lib/guardrail-metrics');
-    const SESSION_ID = process.env.CLAUDE_SESSION_ID || 'default';
-    const metricas = getMetrics(SESSION_ID);
-    const advertencias = diagnosticar(metricas);
-    if (advertencias.length > 0) {
-      console.log('\\n⚠ Diagnóstico:');
-      advertencias.forEach(a => console.log('  - ' + a));
-    } else {
-      console.log('\\n✓ Guardrails sin anomalías detectadas.');
-    }
-  } catch(e) { console.log('(sin datos disponibles)'); }
-"
-```
+El subcomando lee el bridge de la sesión (tmpdir del SO, portable
+Windows/POSIX), imprime la tabla de activaciones/bloqueos/warnings por hook
+y ejecuta el diagnóstico de tasas anómalas — sin datos de sesión muestra el
+resumen vacío.
 
 > El resumen de guardrails también aparece automáticamente al final de cada sesión
 > (hook `resumen-sesion.js`) cuando hay advertencias de tasa anómala.
@@ -314,6 +278,10 @@ Modos: `offline` = funciona leyendo archivos locales; `online` = requiere conexi
 
 ### Uso básico
 
+API del módulo (layout del repo madre; en instalaciones destino vive aplanado
+junto a los hooks instalados — es documentación de referencia, no un comando
+a ejecutar en proyectos consumidores):
+
 ```javascript
 const { listarPorCategoria, listarPorModo, obtenerWidget, obtenerLayoutDefault } =
   require('./scripts/lib/dashboard-widgets');