@saulwade/swl-ses 2.3.0 → 2.3.1

package/comandos/swl/briefing.md

@@ -1,119 +1,119 @@
----
-name: swl:briefing
-description: Briefing proactivo del proyecto bajo demanda. Re-presenta las señales baratas del hook SessionStart (ADRs Propuestos con reevaluación vencida, deuda con trigger por fecha cumplido, nudges sin accionar, gates en calibración, retoma pendiente) y agrega el análisis profundo opt-in que el hook no puede pagar: audit de dependencias del proyecto destino, cobertura vs umbral, hubs del grafo tocados sin revisión, drift de feature-list, y triggers de deuda en prosa libre. Cargar cuando el usuario pide "¿qué hay pendiente?", "¿qué riesgos hay?", "ponme al día", o cuando el digest de sesión sugiere el análisis completo por volumen de señales.
-allowed_tools: ["Read", "Bash", "Glob", "Grep"]
----
-
-# /swl:briefing — Briefing proactivo bajo demanda
-
-Análisis no solicitado del estado del proyecto destino (Fase 12, ADR-0036). El
-hook `session-briefing.js` da el digest barato al abrir sesión; este comando es
-el nivel profundo: re-presenta esas señales Y agrega las que cuestan (deps, grafo,
-cobertura) con degradación funcional si la herramienta no está instalada.
-
-Principio rector: **proponer es barato y siempre permitido; actuar requiere
-autorización del usuario**. Este comando solo propone y analiza — nunca aplica
-cambios sin que el usuario los pida.
-
-## Uso
-
-```
-/swl:briefing            # señales baratas + análisis profundo completo
-/swl:briefing rapido     # solo las 5 señales del hook (sin deps/grafo/cobertura)
-```
-
-## Paso 1 — Señales baratas (mismas del hook)
-
-Ejecuta los recolectores de filesystem y presenta el digest sin tope de 5 (aquí
-sí caben todas, no hay presupuesto de latencia de arranque):
-
-```bash
-# Subcomando del CLI (resuelve cross-scope; ver docs/invocacion-cli-cross-scope.md)
-swl-ses briefing
-# fallback: npx -y @saulwade/swl-ses@latest briefing
-```
-
-Las 5 categorías: `adr-vencido`, `deuda-trigger`, `nudges-pendientes`,
-`gate-calibracion`, `continue-here`. Si `rapido`, terminar aquí.
-
-## Paso 2 — Análisis profundo (opt-in, con degradación)
-
-Para cada herramienta, **validar antes de invocar** (patrón "validar antes de
-invocar"): si no está disponible, reportar "no disponible, omitido" y continuar —
-nunca fallar el briefing por una herramienta ausente.
-
-### 2.1 — Audit de dependencias del proyecto destino
-
-Detectar el ecosistema y correr el audit nativo:
-
-```bash
-# Node
-[ -f package.json ] && npm audit --omit=dev 2>/dev/null | tail -5
-# Python
-[ -f requirements.txt -o -f pyproject.toml ] && (command -v pip-audit >/dev/null && pip-audit 2>/dev/null | tail -5 || echo "pip-audit no instalado — omitido")
-```
-
-Reportar CVEs HIGH/CRITICAL con la acción concreta (`npm audit fix`, bump de
-versión). Sin lockfile o sin gestor → omitir.
-
-### 2.2 — Cobertura vs umbral
-
-Si el proyecto define cobertura, comparar contra el umbral del proyecto (80% por
-defecto). Si no hay reporte reciente, indicar el comando para generarlo en vez de
-correrlo (puede ser caro):
-
-```
-Para medir cobertura: <runner del proyecto> --coverage
-```
-
-### 2.3 — Hubs del grafo tocados sin revisión
-
-Si el MCP `code-review-graph` está disponible (tools `mcp__code-review-graph__*`
-registradas o deferred), consultar los nodos hub modificados en los últimos N
-commits sin revisión asociada. Si no está disponible → omitir con nota.
-
-### 2.4 — Drift de feature-list
-
-```bash
-swl-ses derivar-feature-list --check 2>/dev/null; echo "exit: $?"
-```
-
-Exit 2 → reportar que `HOJA-RUTA.md` y `feature-list.json` divergieron, con la
-acción `swl-ses derivar-feature-list` para regenerar.
-
-### 2.5 — Deuda con trigger en prosa libre
-
-El hook solo evalúa triggers verificables por fecha (D-16). Aquí, leer
-`.planning/DEUDA-TECNICA.md` y evaluar con criterio los triggers en prosa
-("≥2 clientes reportan", "p95 > 60s documentado") contra el estado real del
-proyecto. Reportar los que parezcan cumplidos para revisión del usuario.
-
-## Paso 3 — Presentación y telemetría
-
-Presenta el briefing agrupado por prioridad (continue-here → gates → deuda →
-ADRs → nudges → hallazgos profundos). Cada ítem con su acción ejecutable.
-
-Tras presentar, el usuario decide qué accionar. NO ejecutar acciones de mutación
-(cerrar deuda, promover gates, aplicar fixes) sin que el usuario lo pida — este
-comando es propositivo (separación PROPONER/ACTUAR, ADR-0037 pendiente).
-
-Si el usuario acciona una señal en esta sesión (ejecuta el comando sugerido), esa
-resolución la captura la telemetría de aceptación del hook en la siguiente sesión
-(la señal desaparece del recolector → cuenta como "actuada", D-18).
-
-## Cuándo NO usar este comando
-
-- En cada turno de una sesión: el briefing es por sesión, no por mensaje. El hook
-  ya cubre el inicio; este comando es para cuando el usuario pide el detalle.
-- Para aplicar las acciones propuestas: este comando propone, no ejecuta. Usar el
-  comando concreto de cada señal (`/swl:evolucion-estado`, `/swl:verificar`, etc.).
-- En proyectos sin `.planning/`: no hay señales que recolectar.
-
-## Gotchas
-
-- **Herramienta ausente ≠ error**: si `npm audit`, `pip-audit` o el grafo no están,
-  el briefing los omite con nota y sigue. Nunca abortar por una dependencia opt-in.
-- **No re-listar lo que el hook ya mostró hoy**: el hook aplica dedupe diario; este
-  comando ignora el dedupe a propósito (lo invoca el usuario, quiere ver todo).
-- **`code-review-graph` deferred ≠ ausente**: si las tools aparecen como deferred,
-  cargar su schema con `ToolSearch` antes de concluir que no está disponible.
+---
+name: swl:briefing
+description: Briefing proactivo del proyecto bajo demanda. Re-presenta las señales baratas del hook SessionStart (ADRs Propuestos con reevaluación vencida, deuda con trigger por fecha cumplido, nudges sin accionar, gates en calibración, retoma pendiente) y agrega el análisis profundo opt-in que el hook no puede pagar: audit de dependencias del proyecto destino, cobertura vs umbral, hubs del grafo tocados sin revisión, drift de feature-list, y triggers de deuda en prosa libre. Cargar cuando el usuario pide "¿qué hay pendiente?", "¿qué riesgos hay?", "ponme al día", o cuando el digest de sesión sugiere el análisis completo por volumen de señales.
+allowed_tools: ["Read", "Bash", "Glob", "Grep"]
+---
+
+# /swl:briefing — Briefing proactivo bajo demanda
+
+Análisis no solicitado del estado del proyecto destino (Fase 12, ADR-0036). El
+hook `session-briefing.js` da el digest barato al abrir sesión; este comando es
+el nivel profundo: re-presenta esas señales Y agrega las que cuestan (deps, grafo,
+cobertura) con degradación funcional si la herramienta no está instalada.
+
+Principio rector: **proponer es barato y siempre permitido; actuar requiere
+autorización del usuario**. Este comando solo propone y analiza — nunca aplica
+cambios sin que el usuario los pida.
+
+## Uso
+
+```
+/swl:briefing            # señales baratas + análisis profundo completo
+/swl:briefing rapido     # solo las 5 señales del hook (sin deps/grafo/cobertura)
+```
+
+## Paso 1 — Señales baratas (mismas del hook)
+
+Ejecuta los recolectores de filesystem y presenta el digest sin tope de 5 (aquí
+sí caben todas, no hay presupuesto de latencia de arranque):
+
+```bash
+# Subcomando del CLI (resuelve cross-scope; ver docs/invocacion-cli-cross-scope.md)
+swl-ses briefing
+# fallback: npx -y @saulwade/swl-ses@latest briefing
+```
+
+Las 5 categorías: `adr-vencido`, `deuda-trigger`, `nudges-pendientes`,
+`gate-calibracion`, `continue-here`. Si `rapido`, terminar aquí.
+
+## Paso 2 — Análisis profundo (opt-in, con degradación)
+
+Para cada herramienta, **validar antes de invocar** (patrón "validar antes de
+invocar"): si no está disponible, reportar "no disponible, omitido" y continuar —
+nunca fallar el briefing por una herramienta ausente.
+
+### 2.1 — Audit de dependencias del proyecto destino
+
+Detectar el ecosistema y correr el audit nativo:
+
+```bash
+# Node
+[ -f package.json ] && npm audit --omit=dev 2>/dev/null | tail -5
+# Python
+[ -f requirements.txt -o -f pyproject.toml ] && (command -v pip-audit >/dev/null && pip-audit 2>/dev/null | tail -5 || echo "pip-audit no instalado — omitido")
+```
+
+Reportar CVEs HIGH/CRITICAL con la acción concreta (`npm audit fix`, bump de
+versión). Sin lockfile o sin gestor → omitir.
+
+### 2.2 — Cobertura vs umbral
+
+Si el proyecto define cobertura, comparar contra el umbral del proyecto (80% por
+defecto). Si no hay reporte reciente, indicar el comando para generarlo en vez de
+correrlo (puede ser caro):
+
+```
+Para medir cobertura: <runner del proyecto> --coverage
+```
+
+### 2.3 — Hubs del grafo tocados sin revisión
+
+Si el MCP `code-review-graph` está disponible (tools `mcp__code-review-graph__*`
+registradas o deferred), consultar los nodos hub modificados en los últimos N
+commits sin revisión asociada. Si no está disponible → omitir con nota.
+
+### 2.4 — Drift de feature-list
+
+```bash
+swl-ses derivar-feature-list --check 2>/dev/null; echo "exit: $?"
+```
+
+Exit 2 → reportar que `HOJA-RUTA.md` y `feature-list.json` divergieron, con la
+acción `swl-ses derivar-feature-list` para regenerar.
+
+### 2.5 — Deuda con trigger en prosa libre
+
+El hook solo evalúa triggers verificables por fecha (D-16). Aquí, leer
+`.planning/DEUDA-TECNICA.md` y evaluar con criterio los triggers en prosa
+("≥2 clientes reportan", "p95 > 60s documentado") contra el estado real del
+proyecto. Reportar los que parezcan cumplidos para revisión del usuario.
+
+## Paso 3 — Presentación y telemetría
+
+Presenta el briefing agrupado por prioridad (continue-here → gates → deuda →
+ADRs → nudges → hallazgos profundos). Cada ítem con su acción ejecutable.
+
+Tras presentar, el usuario decide qué accionar. NO ejecutar acciones de mutación
+(cerrar deuda, promover gates, aplicar fixes) sin que el usuario lo pida — este
+comando es propositivo (separación PROPONER/ACTUAR, ADR-0037 pendiente).
+
+Si el usuario acciona una señal en esta sesión (ejecuta el comando sugerido), esa
+resolución la captura la telemetría de aceptación del hook en la siguiente sesión
+(la señal desaparece del recolector → cuenta como "actuada", D-18).
+
+## Cuándo NO usar este comando
+
+- En cada turno de una sesión: el briefing es por sesión, no por mensaje. El hook
+  ya cubre el inicio; este comando es para cuando el usuario pide el detalle.
+- Para aplicar las acciones propuestas: este comando propone, no ejecuta. Usar el
+  comando concreto de cada señal (`/swl:evolucion-estado`, `/swl:verificar`, etc.).
+- En proyectos sin `.planning/`: no hay señales que recolectar.
+
+## Gotchas
+
+- **Herramienta ausente ≠ error**: si `npm audit`, `pip-audit` o el grafo no están,
+  el briefing los omite con nota y sigue. Nunca abortar por una dependencia opt-in.
+- **No re-listar lo que el hook ya mostró hoy**: el hook aplica dedupe diario; este
+  comando ignora el dedupe a propósito (lo invoca el usuario, quiere ver todo).
+- **`code-review-graph` deferred ≠ ausente**: si las tools aparecen como deferred,
+  cargar su schema con `ToolSearch` antes de concluir que no está disponible.