@saulwade/swl-ses 2.5.3 → 2.6.0

package/comandos/swl/revisar-impacto.md

@@ -1,201 +1,201 @@
----
-name: swl:revisar-impacto
-description: Analiza el impacto estructural de cambios usando el grafo de dependencias SWL. Proporciona blast radius topológico real, god nodes, comunidades y conexiones sorpresivas. Potenciado por graph-builder.py + graph-analyze.py (graphify-3 patterns).
-allowed_tools: ["Bash", "Read"]
----
-
-# /swl:revisar-impacto — Análisis de impacto estructural
-
-Usa el grafo de dependencias de swl-ses para responder:
-¿qué se rompe si modifico esto? ¿cuál es el riesgo real de estos cambios?
-
-## Uso
-
-```
-/swl:revisar-impacto                          — Resumen topológico general
-/swl:revisar-impacto build                    — Construir/reconstruir el grafo
-/swl:revisar-impacto build --force            — Reconstruir ignorando cache SHA256
-/swl:revisar-impacto status                   — Estado del grafo actual
-/swl:revisar-impacto impacto <nombre>         — Blast radius de un componente
-/swl:revisar-impacto god_nodes [--top N]      — Componentes más conectados
-/swl:revisar-impacto comunidades              — Estructura modular del sistema
-/swl:revisar-impacto sorpresivo               — Acoplamiento oculto cross-community
-/swl:revisar-impacto preguntas                — Preguntas arquitectónicas del grafo
-/swl:revisar-impacto diff <grafo1> <grafo2>   — Cambios entre dos snapshots
-```
-
----
-
-## Paso 0 — Verificar grafo disponible
-
-```bash
-ls .planning/graph.json .planning/REPORTE-GRAFO.md 2>/dev/null \
-  && echo "GRAFO DISPONIBLE" || echo "GRAFO NO CONSTRUIDO"
-```
-
-Si el grafo no existe, construirlo con `build` antes de cualquier análisis.
-
----
-
-## Subcomando: build
-
-Construye el grafo de dependencias desde los metadatos del sistema.
-Parsea: `agentes/*.md`, `habilidades/*/SKILL.md`, `hooks/*.js`, `hooks/lib/*.js`, `comandos/swl/*.md`.
-
-```bash
-python scripts/lib/graph-builder.py
-```
-
-Con flag `--force` ignora el cache SHA256 y reparse todos los archivos:
-
-```bash
-python scripts/lib/graph-builder.py --force
-```
-
-Salidas generadas:
-- `.planning/graph.json` — grafo persistente (networkx node-link format)
-- `.planning/REPORTE-GRAFO.md` — reporte legible para agentes
-- `.planning/graph-cache.json` — cache SHA256 por archivo
-
----
-
-## Subcomando: status
-
-```bash
-python scripts/lib/graph-builder.py --stats
-```
-
-Muestra conteo de nodos por tipo y aristas totales.
-
----
-
-## Subcomando: impacto (blast radius)
-
-Calcula qué componentes quedan afectados si un nodo cambia.
-Usa BFS en el grafo invertido a profundidad 3.
-
-```bash
-python scripts/lib/graph-analyze.py blast_radius <nombre>
-# Ejemplos:
-python scripts/lib/graph-analyze.py blast_radius event-bus
-python scripts/lib/graph-analyze.py blast_radius fastapi-experto
-python scripts/lib/graph-analyze.py blast_radius atomic-write
-```
-
-Interpretar el resultado:
-- **dependientes**: componentes que dependen de `<nombre>` — se ven afectados si cambia
-- **dependencias**: qué usa `<nombre>` — se ven afectados si fallan
-- **grado alto** → blast radius alto → mayor precaución al modificar
-
----
-
-## Subcomando: god_nodes
-
-Identifica los componentes más conectados del sistema (single points of failure).
-
-```bash
-python scripts/lib/graph-analyze.py god_nodes --top 10
-```
-
-Un god node con grado > 5 debe considerarse un componente crítico.
-Modificarlo requiere revisión de todos sus dependientes.
-
----
-
-## Subcomando: comunidades
-
-Detecta módulos funcionales automáticamente mediante Louvain community detection.
-
-```bash
-python scripts/lib/graph-cluster.py
-# Salida JSON:
-python scripts/lib/graph-cluster.py json
-```
-
-Interpretar:
-- **cohesión < 0.10** con ≥ 5 nodos → comunidad candidata a refactoring
-- **comunidades bien cohesionadas** → módulos funcionalmente coherentes
-
----
-
-## Subcomando: sorpresivo
-
-Detecta acoplamiento oculto: aristas cross-community inesperadas.
-
-```bash
-python scripts/lib/graph-analyze.py sorpresivo
-```
-
-Una conexión "sorpresiva" es aquella que cruza comunidades y conecta tipos
-distintos de componentes — acoplamiento que debería hacerse explícito.
-
----
-
-## Subcomando: preguntas
-
-Genera preguntas arquitectónicas derivadas de la topología del grafo.
-
-```bash
-python scripts/lib/graph-analyze.py preguntas
-```
-
-Fuentes: bridge nodes (alta betweenness), god nodes (alto grado), nodos huérfanos,
-comunidades de baja cohesión. Alimentar al `arquitecto-swl` con estas preguntas.
-
----
-
-## Subcomando: diff
-
-Compara dos snapshots del grafo para entender qué cambió estructuralmente.
-
-```bash
-# Guardar snapshot antes de los cambios:
-cp .planning/graph.json .planning/graph-before.json
-
-# Hacer cambios, reconstruir grafo:
-python scripts/lib/graph-builder.py --force
-
-# Comparar:
-python scripts/lib/graph-analyze.py diff .planning/graph-before.json .planning/graph.json
-```
-
----
-
-## Flujo recomendado pre-modificación de componente crítico
-
-```bash
-# 1. Verificar que el grafo está actualizado
-python scripts/lib/graph-builder.py
-
-# 2. Calcular blast radius del componente a modificar
-python scripts/lib/graph-analyze.py blast_radius <nombre>
-
-# 3. Ver si es un god node
-python scripts/lib/graph-analyze.py god_nodes --top 20 | grep <nombre>
-
-# 4. Verificar comunidad del componente
-python scripts/lib/graph-cluster.py json | python -c "
-import json,sys
-data=json.load(sys.stdin)
-nombre='<nombre>'
-for cid,c in data.items():
-    if nombre in c['nodos']:
-        print(f'Comunidad {cid}: {c[\"etiqueta\"]} (cohesión {c[\"cohesion\"]})')
-"
-```
-
----
-
-## Cómo usar REPORTE-GRAFO.md
-
-El archivo `.planning/REPORTE-GRAFO.md` es inyectado automáticamente por el hook
-`grafo-contexto.js` antes de cualquier búsqueda de archivos (Glob/Grep/Read).
-
-Esto significa que los agentes tienen contexto del grafo ANTES de leer archivos raw,
-reduciendo el número de tool calls para mapear el codebase.
-
-Para leer el reporte directamente:
-
-```bash
-cat .planning/REPORTE-GRAFO.md
-```
+---
+name: swl:revisar-impacto
+description: Analiza el impacto estructural de cambios usando el grafo de dependencias SWL. Proporciona blast radius topológico real, god nodes, comunidades y conexiones sorpresivas. Potenciado por graph-builder.py + graph-analyze.py (graphify-3 patterns).
+allowed_tools: ["Bash", "Read"]
+---
+
+# /swl:revisar-impacto — Análisis de impacto estructural
+
+Usa el grafo de dependencias de swl-ses para responder:
+¿qué se rompe si modifico esto? ¿cuál es el riesgo real de estos cambios?
+
+## Uso
+
+```
+/swl:revisar-impacto                          — Resumen topológico general
+/swl:revisar-impacto build                    — Construir/reconstruir el grafo
+/swl:revisar-impacto build --force            — Reconstruir ignorando cache SHA256
+/swl:revisar-impacto status                   — Estado del grafo actual
+/swl:revisar-impacto impacto <nombre>         — Blast radius de un componente
+/swl:revisar-impacto god_nodes [--top N]      — Componentes más conectados
+/swl:revisar-impacto comunidades              — Estructura modular del sistema
+/swl:revisar-impacto sorpresivo               — Acoplamiento oculto cross-community
+/swl:revisar-impacto preguntas                — Preguntas arquitectónicas del grafo
+/swl:revisar-impacto diff <grafo1> <grafo2>   — Cambios entre dos snapshots
+```
+
+---
+
+## Paso 0 — Verificar grafo disponible
+
+```bash
+ls .planning/graph.json .planning/REPORTE-GRAFO.md 2>/dev/null \
+  && echo "GRAFO DISPONIBLE" || echo "GRAFO NO CONSTRUIDO"
+```
+
+Si el grafo no existe, construirlo con `build` antes de cualquier análisis.
+
+---
+
+## Subcomando: build
+
+Construye el grafo de dependencias desde los metadatos del sistema.
+Parsea: `agentes/*.md`, `habilidades/*/SKILL.md`, `hooks/*.js`, `hooks/lib/*.js`, `comandos/swl/*.md`.
+
+```bash
+python scripts/lib/graph-builder.py
+```
+
+Con flag `--force` ignora el cache SHA256 y reparse todos los archivos:
+
+```bash
+python scripts/lib/graph-builder.py --force
+```
+
+Salidas generadas:
+- `.planning/graph.json` — grafo persistente (networkx node-link format)
+- `.planning/REPORTE-GRAFO.md` — reporte legible para agentes
+- `.planning/graph-cache.json` — cache SHA256 por archivo
+
+---
+
+## Subcomando: status
+
+```bash
+python scripts/lib/graph-builder.py --stats
+```
+
+Muestra conteo de nodos por tipo y aristas totales.
+
+---
+
+## Subcomando: impacto (blast radius)
+
+Calcula qué componentes quedan afectados si un nodo cambia.
+Usa BFS en el grafo invertido a profundidad 3.
+
+```bash
+python scripts/lib/graph-analyze.py blast_radius <nombre>
+# Ejemplos:
+python scripts/lib/graph-analyze.py blast_radius event-bus
+python scripts/lib/graph-analyze.py blast_radius fastapi-experto
+python scripts/lib/graph-analyze.py blast_radius atomic-write
+```
+
+Interpretar el resultado:
+- **dependientes**: componentes que dependen de `<nombre>` — se ven afectados si cambia
+- **dependencias**: qué usa `<nombre>` — se ven afectados si fallan
+- **grado alto** → blast radius alto → mayor precaución al modificar
+
+---
+
+## Subcomando: god_nodes
+
+Identifica los componentes más conectados del sistema (single points of failure).
+
+```bash
+python scripts/lib/graph-analyze.py god_nodes --top 10
+```
+
+Un god node con grado > 5 debe considerarse un componente crítico.
+Modificarlo requiere revisión de todos sus dependientes.
+
+---
+
+## Subcomando: comunidades
+
+Detecta módulos funcionales automáticamente mediante Louvain community detection.
+
+```bash
+python scripts/lib/graph-cluster.py
+# Salida JSON:
+python scripts/lib/graph-cluster.py json
+```
+
+Interpretar:
+- **cohesión < 0.10** con ≥ 5 nodos → comunidad candidata a refactoring
+- **comunidades bien cohesionadas** → módulos funcionalmente coherentes
+
+---
+
+## Subcomando: sorpresivo
+
+Detecta acoplamiento oculto: aristas cross-community inesperadas.
+
+```bash
+python scripts/lib/graph-analyze.py sorpresivo
+```
+
+Una conexión "sorpresiva" es aquella que cruza comunidades y conecta tipos
+distintos de componentes — acoplamiento que debería hacerse explícito.
+
+---
+
+## Subcomando: preguntas
+
+Genera preguntas arquitectónicas derivadas de la topología del grafo.
+
+```bash
+python scripts/lib/graph-analyze.py preguntas
+```
+
+Fuentes: bridge nodes (alta betweenness), god nodes (alto grado), nodos huérfanos,
+comunidades de baja cohesión. Alimentar al `arquitecto-swl` con estas preguntas.
+
+---
+
+## Subcomando: diff
+
+Compara dos snapshots del grafo para entender qué cambió estructuralmente.
+
+```bash
+# Guardar snapshot antes de los cambios:
+cp .planning/graph.json .planning/graph-before.json
+
+# Hacer cambios, reconstruir grafo:
+python scripts/lib/graph-builder.py --force
+
+# Comparar:
+python scripts/lib/graph-analyze.py diff .planning/graph-before.json .planning/graph.json
+```
+
+---
+
+## Flujo recomendado pre-modificación de componente crítico
+
+```bash
+# 1. Verificar que el grafo está actualizado
+python scripts/lib/graph-builder.py
+
+# 2. Calcular blast radius del componente a modificar
+python scripts/lib/graph-analyze.py blast_radius <nombre>
+
+# 3. Ver si es un god node
+python scripts/lib/graph-analyze.py god_nodes --top 20 | grep <nombre>
+
+# 4. Verificar comunidad del componente
+python scripts/lib/graph-cluster.py json | python -c "
+import json,sys
+data=json.load(sys.stdin)
+nombre='<nombre>'
+for cid,c in data.items():
+    if nombre in c['nodos']:
+        print(f'Comunidad {cid}: {c[\"etiqueta\"]} (cohesión {c[\"cohesion\"]})')
+"
+```
+
+---
+
+## Cómo usar REPORTE-GRAFO.md
+
+El archivo `.planning/REPORTE-GRAFO.md` es inyectado automáticamente por el hook
+`grafo-contexto.js` antes de cualquier búsqueda de archivos (Glob/Grep/Read).
+
+Esto significa que los agentes tienen contexto del grafo ANTES de leer archivos raw,
+reduciendo el número de tool calls para mapear el codebase.
+
+Para leer el reporte directamente:
+
+```bash
+cat .planning/REPORTE-GRAFO.md
+```