@saulwade/swl-ses 1.3.3 → 1.3.5

package/habilidades/swl-claudemd/SKILL.md

@@ -1,220 +1,220 @@
----
-name: swl-claudemd
-description: Tratamiento profesional de CLAUDE.md según best practices Anthropic (ADR-0016). Cubre auditoría (líneas totales, bullets gigantes, secciones canónicas, @references, placeholders), refactor (extracción a archivos referenciados con @), generación de templates (init-user para preferencias personales transversales en ~/.claude/CLAUDE.md, init-project para CLAUDE.md raíz del proyecto detectando stack). Cargar cuando se invoque /swl:claudemd o cuando el hook claudemd-bloat-detector sugiera intervención.
-version: "1.0.0"
-herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
-exclusiones:
-  - "No cargar para editar reglas globales en ~/.claude/rules/ — usar Edit directo."
-  - "No cargar para crear ADRs — usar habilidades/doc-coauthoring o Write directo."
-  - "No cargar para validar otros archivos (.md de docs, READMEs) — solo CLAUDE.md tiene contrato canónico."
-  - "No cargar para generar el bloque del installer en CLAUDE.md de proyectos destino — eso lo hace scripts/lib/transformadores/claude.js."
-evolvable: true
----
-
-# Habilidad: Tratamiento profesional de CLAUDE.md
-
-## Propósito
-
-Aplicar las cinco recomendaciones del video oficial Anthropic
-*"The CLAUDE.md file"* (`temp/YouTube · O0FGCxkHM-U.md`) como mecanismo
-verificable y mantenible:
-
-1. **Compacto** — empieza sin uno, agrega solo lo que tengas que corregir
-2. **Stack arriba** — lenguaje, framework, ORM, BD
-3. **Commands** — cómo correr dev, tests, lint, build
-4. **Code style** — convenciones de indentación, exports, nombrado
-5. **Conventions** — dónde van las cosas, qué patrones preferir
-
-Más dos prácticas auxiliares del video:
-
-- **`@filepath`** para referenciar docs en lugar de duplicar contenido
-- **"Ask Claude to save to memory"** — el archivo crece con correcciones
-  explícitas, no por adelantar reglas hipotéticas
-
-## Cuándo cargar
-
-- El usuario invoca `/swl:claudemd [audit|check|refactor|init-user|init-project]`
-- El hook `claudemd-bloat-detector` emite nudge sugiriendo `/swl:claudemd refactor`
-- El usuario pregunta "¿está bien mi CLAUDE.md?" o "¿cómo mejoro mi CLAUDE.md?"
-- Se está generando un proyecto nuevo y se necesita CLAUDE.md raíz
-- Se está cambiando de máquina y se necesita transportar `~/.claude/CLAUDE.md`
-
-## Cuándo NO cargar
-
-- El usuario quiere editar `~/.claude/rules/*.md` (reglas globales) — usar Edit directo
-- El usuario quiere validar otros `.md` (READMEs, docs/) — no aplica el contrato canónico de CLAUDE.md
-- El usuario quiere generar el bloque del installer — eso lo hace `scripts/lib/transformadores/claude.js`
-- El usuario quiere crear un ADR — usar `Skill("doc-coauthoring")` o Write directo
-
----
-
-## Subcomando: audit
-
-Ejecuta el auditor determinista:
-
-```bash
-node scripts/auditar-claudemd.js
-node scripts/auditar-claudemd.js --json    # para parsing
-node scripts/auditar-claudemd.js --strict  # exit 1 si WARN
-```
-
-El auditor verifica seis dimensiones:
-
-| Dimensión | Regla | Severidad |
-|---|---|---|
-| Existencia | Archivo presente en `./CLAUDE.md` o `./.claude/CLAUDE.md` | ERROR si ausente |
-| Tamaño total | Líneas ≤ `SWL_CLAUDEMD_MAX_LINES` (default 200) | WARN |
-| Bullets monolíticos | Cada bullet/párrafo ≤ `SWL_CLAUDEMD_MAX_BULLET_CHARS` (default 1000). Tablas y bloques de código se ignoran | WARN |
-| Secciones canónicas | Stack, Comandos, Code style, Conventions presentes | WARN |
-| @references | Archivos >80 líneas usan al menos un `@docs/...md` | WARN |
-| Placeholders | `[TBD]`, `[TODO]`, `[COMPLETAR]` | ERROR |
-
-Veredicto final: ERROR → WARN → OK (el más severo gana).
-
-### Cómo interpretar los resultados
-
-- **OK**: el archivo cumple. No hay acción requerida.
-- **WARN líneas**: el archivo creció demasiado. Ejecuta `refactor` para
-  identificar candidatos a extracción.
-- **WARN bullet gigante**: un bullet/párrafo es ilegible. Convertirlo a
-  tabla, lista jerárquica, o extraer su contenido a archivo separado.
-- **WARN secciones ausentes**: las secciones canónicas Anthropic no
-  están. Si el archivo es proyecto greenfield, agregarlas. Si es CLAUDE.md
-  de overview/meta-sistema, considerar si aplica el contrato.
-- **WARN sin @references**: el archivo es grande pero no enlaza nada
-  externo. Identificar contenido duplicable a `@docs/`, `@.planning/`, etc.
-- **ERROR placeholders**: bloqueador. Resolver antes de commitear.
-
----
-
-## Subcomando: refactor
-
-**No modifica archivos** — propone diff. El usuario decide aplicar.
-
-### Algoritmo
-
-1. Lee `CLAUDE.md` actual.
-2. Para cada bullet/párrafo > `MAX_BULLET_CHARS`:
-   - Si contiene **una sola lista de items homogéneos** → propone tabla
-   - Si contiene **definiciones técnicas extensas** → propone extracción a `docs/[tema].md`
-   - Si contiene **enumeración de variables/configuración** → propone extracción a `docs/variables-[scope].md`
-3. Para cada sección > 50 líneas:
-   - Identifica el "tema" del header
-   - Propone `docs/[tema-kebab].md` y reemplazo en CLAUDE.md por:
-     `Para detalles ver @docs/[tema].md`
-4. Imprime diff propuesto en formato unified.
-
-### Patrones de extracción típicos
-
-| Si la sección/bullet contiene… | Mover a… |
-|---|---|
-| Variables de entorno opt-in | `docs/variables-entorno.md` |
-| Reglas de gobernanza extensas | `docs/gobernanza.md` |
-| Catálogo completo de comandos | `COMANDOS.md` (referenciar) |
-| Mapa de propagación detallado | `docs/mapa-propagacion.md` |
-| Convenciones por capa | `docs/convenciones-{capa}.md` |
-| Lista de dependencias / stack histórico | `docs/stack-historico.md` |
-| Decisiones puntuales antiguas | ADR en `.planning/adrs/` |
-
-### Anti-patrones de refactor
-
-- **NO extraer reglas de máxima prioridad** — esas DEBEN estar en CLAUDE.md raíz
-- **NO extraer la sección Stack** — es la primera info que Claude necesita
-- **NO extraer la sección Commands** — son acción inmediata, deben estar visibles
-- **NO crear más de 3 archivos `@`-referenciados nuevos en un solo refactor** — fragmentar demasiado dispersa el contexto
-
----
-
-## Subcomando: init-user
-
-Genera `~/.claude/CLAUDE.md` (en Windows: `%USERPROFILE%\.claude\CLAUDE.md`)
-con template de preferencias personales si NO existe. Si existe, sugiere
-secciones faltantes pero NO sobreescribe.
-
-### Pasos
-
-1. Detectar la ruta:
-   - Linux/macOS: `$HOME/.claude/CLAUDE.md`
-   - Windows: `$env:USERPROFILE/.claude/CLAUDE.md` (en PowerShell)
-2. Si existe → leer, identificar secciones faltantes, sugerir patches
-3. Si no existe → crear directorio `~/.claude/` si falta, escribir template
-
-### Template
-
-Ver template completo en el comando `/swl:claudemd` sección `init-user`.
-
-Las secciones canónicas para user-level son DISTINTAS de project-level:
-
-| Sección | Project-level | User-level |
-|---|---|---|
-| Stack | Sí — del proyecto | No (varía por proyecto) |
-| Comandos | Sí — del proyecto | No |
-| Code style | Sí — convenciones del equipo | Sí — preferencias personales (indent, naming favorito) |
-| Conventions | Sí — del proyecto | No |
-| Mi rol y stack preferido | No | Sí |
-| Estilo de comunicación | No | Sí |
-| Patrones que aplico siempre | No | Sí — meta-preferencias cross-project |
-
----
-
-## Subcomando: init-project
-
-Genera `./CLAUDE.md` raíz del proyecto detectando stack actual.
-
-### Pasos
-
-1. Verificar que `./CLAUDE.md` NO exista. Si existe → mensaje "ya existe,
-   considera `/swl:claudemd refactor`" y salir sin tocar.
-2. Ejecutar `detectarStackDetallado(process.cwd())` (de
-   `scripts/lib/detectar-stack-detallado.js`).
-3. Generar archivo con secciones pobladas:
-   - **Stack**: lenguaje + framework + ORM + package manager detectados
-   - **Comandos**: npm scripts detectados o comandos típicos por lenguaje
-   - **Code style**: placeholders explícitos (`<!-- pendiente: definir convención de X -->`)
-   - **Conventions**: placeholders explícitos
-   - **@references**: enlazar a `.planning/PROYECTO.md`, `README.md`,
-     `CONTRIBUTING.md` solo si existen
-4. Imprimir mensaje con próximo paso: "ejecuta `/swl:claudemd audit`
-   para verificar".
-
----
-
-## Gotchas / Errores comunes no obvios
-
-- **Marcar tablas como bullets gigantes**: el detector debe excluir
-  líneas que empiezan con `|` (tablas Markdown). Sin ese filtro genera
-  falsos positivos en cualquier CLAUDE.md con tablas. Implementado en
-  `scripts/auditar-claudemd.js` función `detectarBulletsGigantes`.
-- **Marcar bloques de código como bullets gigantes**: igual que tablas
-  — el detector entra en modo "code fence" al ver ` ``` ` y no cuenta
-  esas líneas. Sin ese filtro un script Bash de 50 líneas en CLAUDE.md
-  rompe la auditoría.
-- **`refactor` que termina escribiendo el archivo**: el subcomando
-  refactor SOLO debe imprimir diff. Si modifica el archivo viola el
-  principio "el usuario decide". Cualquier modificación destructiva debe
-  ser explícita y confirmada por el usuario.
-- **`init-project` sobreescribiendo CLAUDE.md existente**: el usuario
-  puede tener un CLAUDE.md curado con valor irrecuperable. NUNCA
-  sobreescribir — sugerir refactor.
-- **Templates con `[TBD]` que después fallan auditoría**: los templates
-  generados por `init-user` y `init-project` usan `<!-- pendiente: ... -->`
-  HTML comments en lugar de `[TBD]` para que el auditor no los marque
-  como ERROR placeholders. Comments HTML son ignorados por el regex.
-- **Aplicar el contrato canónico a CLAUDE.md de subdirectorios**: si el
-  proyecto adopta jerarquía (ADR-0007), los CLAUDE.md de subdirectorios
-  pueden NO tener todas las secciones canónicas (porque heredan del root).
-  Por ahora el auditor aplica el contrato uniforme; si el ADR-0007 se
-  acepta, el auditor debe distinguir root vs subdirectorio.
-
-## Señales de alerta
-
-Detente y escala si:
-
-- El usuario pide `init-project` en un directorio que ya tiene CLAUDE.md
-  con >100 líneas de contenido custom (riesgo: pérdida de información)
-- `audit` reporta WARN líneas pero el contenido es legítimamente
-  necesario (ej. listas grandes de comandos sin posibilidad de extracción
-  útil) — sugerir ajustar `SWL_CLAUDEMD_MAX_LINES`, no extraer por extraer
-- El usuario pide `refactor` y propone extracciones que dispersarían
-  contexto crítico (ej. mover "Reglas de máxima prioridad") — rechazar
-  con explicación del anti-patrón
+---
+name: swl-claudemd
+description: Conocimiento operacional para auditar y mantener archivos CLAUDE.md — contrato canónico de secciones (best practices Anthropic, ADR-0016), umbrales de bloat (líneas totales, bullets gigantes, placeholders, @references rotas), reglas de extracción a archivos referenciados con @, y plantillas de inicialización (init-user para ~/.claude/CLAUDE.md, init-project para CLAUDE.md raíz detectando stack). Provee las reglas; el comando /swl:claudemd ejecuta el flujo. Cargar desde ese comando o cuando el hook claudemd-bloat-detector sugiera intervención.
+version: "1.0.1"
+herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
+exclusiones:
+  - "No cargar para editar reglas globales en ~/.claude/rules/ — usar Edit directo."
+  - "No cargar para crear ADRs — usar habilidades/doc-coauthoring o Write directo."
+  - "No cargar para validar otros archivos (.md de docs, READMEs) — solo CLAUDE.md tiene contrato canónico."
+  - "No cargar para generar el bloque del installer en CLAUDE.md de proyectos destino — eso lo hace scripts/lib/transformadores/claude.js."
+evolvable: true
+---
+
+# Habilidad: Tratamiento profesional de CLAUDE.md
+
+## Propósito
+
+Aplicar las cinco recomendaciones del video oficial Anthropic
+*"The CLAUDE.md file"* (`temp/YouTube · O0FGCxkHM-U.md`) como mecanismo
+verificable y mantenible:
+
+1. **Compacto** — empieza sin uno, agrega solo lo que tengas que corregir
+2. **Stack arriba** — lenguaje, framework, ORM, BD
+3. **Commands** — cómo correr dev, tests, lint, build
+4. **Code style** — convenciones de indentación, exports, nombrado
+5. **Conventions** — dónde van las cosas, qué patrones preferir
+
+Más dos prácticas auxiliares del video:
+
+- **`@filepath`** para referenciar docs en lugar de duplicar contenido
+- **"Ask Claude to save to memory"** — el archivo crece con correcciones
+  explícitas, no por adelantar reglas hipotéticas
+
+## Cuándo cargar
+
+- El usuario invoca `/swl:claudemd [audit|check|refactor|init-user|init-project]`
+- El hook `claudemd-bloat-detector` emite nudge sugiriendo `/swl:claudemd refactor`
+- El usuario pregunta "¿está bien mi CLAUDE.md?" o "¿cómo mejoro mi CLAUDE.md?"
+- Se está generando un proyecto nuevo y se necesita CLAUDE.md raíz
+- Se está cambiando de máquina y se necesita transportar `~/.claude/CLAUDE.md`
+
+## Cuándo NO cargar
+
+- El usuario quiere editar `~/.claude/rules/*.md` (reglas globales) — usar Edit directo
+- El usuario quiere validar otros `.md` (READMEs, docs/) — no aplica el contrato canónico de CLAUDE.md
+- El usuario quiere generar el bloque del installer — eso lo hace `scripts/lib/transformadores/claude.js`
+- El usuario quiere crear un ADR — usar `Skill("doc-coauthoring")` o Write directo
+
+---
+
+## Subcomando: audit
+
+Ejecuta el auditor determinista:
+
+```bash
+node scripts/auditar-claudemd.js
+node scripts/auditar-claudemd.js --json    # para parsing
+node scripts/auditar-claudemd.js --strict  # exit 1 si WARN
+```
+
+El auditor verifica seis dimensiones:
+
+| Dimensión | Regla | Severidad |
+|---|---|---|
+| Existencia | Archivo presente en `./CLAUDE.md` o `./.claude/CLAUDE.md` | ERROR si ausente |
+| Tamaño total | Líneas ≤ `SWL_CLAUDEMD_MAX_LINES` (default 200) | WARN |
+| Bullets monolíticos | Cada bullet/párrafo ≤ `SWL_CLAUDEMD_MAX_BULLET_CHARS` (default 1000). Tablas y bloques de código se ignoran | WARN |
+| Secciones canónicas | Stack, Comandos, Code style, Conventions presentes | WARN |
+| @references | Archivos >80 líneas usan al menos un `@docs/...md` | WARN |
+| Placeholders | `[TBD]`, `[TODO]`, `[COMPLETAR]` | ERROR |
+
+Veredicto final: ERROR → WARN → OK (el más severo gana).
+
+### Cómo interpretar los resultados
+
+- **OK**: el archivo cumple. No hay acción requerida.
+- **WARN líneas**: el archivo creció demasiado. Ejecuta `refactor` para
+  identificar candidatos a extracción.
+- **WARN bullet gigante**: un bullet/párrafo es ilegible. Convertirlo a
+  tabla, lista jerárquica, o extraer su contenido a archivo separado.
+- **WARN secciones ausentes**: las secciones canónicas Anthropic no
+  están. Si el archivo es proyecto greenfield, agregarlas. Si es CLAUDE.md
+  de overview/meta-sistema, considerar si aplica el contrato.
+- **WARN sin @references**: el archivo es grande pero no enlaza nada
+  externo. Identificar contenido duplicable a `@docs/`, `@.planning/`, etc.
+- **ERROR placeholders**: bloqueador. Resolver antes de commitear.
+
+---
+
+## Subcomando: refactor
+
+**No modifica archivos** — propone diff. El usuario decide aplicar.
+
+### Algoritmo
+
+1. Lee `CLAUDE.md` actual.
+2. Para cada bullet/párrafo > `MAX_BULLET_CHARS`:
+   - Si contiene **una sola lista de items homogéneos** → propone tabla
+   - Si contiene **definiciones técnicas extensas** → propone extracción a `docs/[tema].md`
+   - Si contiene **enumeración de variables/configuración** → propone extracción a `docs/variables-[scope].md`
+3. Para cada sección > 50 líneas:
+   - Identifica el "tema" del header
+   - Propone `docs/[tema-kebab].md` y reemplazo en CLAUDE.md por:
+     `Para detalles ver @docs/[tema].md`
+4. Imprime diff propuesto en formato unified.
+
+### Patrones de extracción típicos
+
+| Si la sección/bullet contiene… | Mover a… |
+|---|---|
+| Variables de entorno opt-in | `docs/variables-entorno.md` |
+| Reglas de gobernanza extensas | `docs/gobernanza.md` |
+| Catálogo completo de comandos | `COMANDOS.md` (referenciar) |
+| Mapa de propagación detallado | `docs/mapa-propagacion.md` |
+| Convenciones por capa | `docs/convenciones-{capa}.md` |
+| Lista de dependencias / stack histórico | `docs/stack-historico.md` |
+| Decisiones puntuales antiguas | ADR en `.planning/adrs/` |
+
+### Anti-patrones de refactor
+
+- **NO extraer reglas de máxima prioridad** — esas DEBEN estar en CLAUDE.md raíz
+- **NO extraer la sección Stack** — es la primera info que Claude necesita
+- **NO extraer la sección Commands** — son acción inmediata, deben estar visibles
+- **NO crear más de 3 archivos `@`-referenciados nuevos en un solo refactor** — fragmentar demasiado dispersa el contexto
+
+---
+
+## Subcomando: init-user
+
+Genera `~/.claude/CLAUDE.md` (en Windows: `%USERPROFILE%\.claude\CLAUDE.md`)
+con template de preferencias personales si NO existe. Si existe, sugiere
+secciones faltantes pero NO sobreescribe.
+
+### Pasos
+
+1. Detectar la ruta:
+   - Linux/macOS: `$HOME/.claude/CLAUDE.md`
+   - Windows: `$env:USERPROFILE/.claude/CLAUDE.md` (en PowerShell)
+2. Si existe → leer, identificar secciones faltantes, sugerir patches
+3. Si no existe → crear directorio `~/.claude/` si falta, escribir template
+
+### Template
+
+Ver template completo en el comando `/swl:claudemd` sección `init-user`.
+
+Las secciones canónicas para user-level son DISTINTAS de project-level:
+
+| Sección | Project-level | User-level |
+|---|---|---|
+| Stack | Sí — del proyecto | No (varía por proyecto) |
+| Comandos | Sí — del proyecto | No |
+| Code style | Sí — convenciones del equipo | Sí — preferencias personales (indent, naming favorito) |
+| Conventions | Sí — del proyecto | No |
+| Mi rol y stack preferido | No | Sí |
+| Estilo de comunicación | No | Sí |
+| Patrones que aplico siempre | No | Sí — meta-preferencias cross-project |
+
+---
+
+## Subcomando: init-project
+
+Genera `./CLAUDE.md` raíz del proyecto detectando stack actual.
+
+### Pasos
+
+1. Verificar que `./CLAUDE.md` NO exista. Si existe → mensaje "ya existe,
+   considera `/swl:claudemd refactor`" y salir sin tocar.
+2. Ejecutar `detectarStackDetallado(process.cwd())` (de
+   `scripts/lib/detectar-stack-detallado.js`).
+3. Generar archivo con secciones pobladas:
+   - **Stack**: lenguaje + framework + ORM + package manager detectados
+   - **Comandos**: npm scripts detectados o comandos típicos por lenguaje
+   - **Code style**: placeholders explícitos (`<!-- pendiente: definir convención de X -->`)
+   - **Conventions**: placeholders explícitos
+   - **@references**: enlazar a `.planning/PROYECTO.md`, `README.md`,
+     `CONTRIBUTING.md` solo si existen
+4. Imprimir mensaje con próximo paso: "ejecuta `/swl:claudemd audit`
+   para verificar".
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+- **Marcar tablas como bullets gigantes**: el detector debe excluir
+  líneas que empiezan con `|` (tablas Markdown). Sin ese filtro genera
+  falsos positivos en cualquier CLAUDE.md con tablas. Implementado en
+  `scripts/auditar-claudemd.js` función `detectarBulletsGigantes`.
+- **Marcar bloques de código como bullets gigantes**: igual que tablas
+  — el detector entra en modo "code fence" al ver ` ``` ` y no cuenta
+  esas líneas. Sin ese filtro un script Bash de 50 líneas en CLAUDE.md
+  rompe la auditoría.
+- **`refactor` que termina escribiendo el archivo**: el subcomando
+  refactor SOLO debe imprimir diff. Si modifica el archivo viola el
+  principio "el usuario decide". Cualquier modificación destructiva debe
+  ser explícita y confirmada por el usuario.
+- **`init-project` sobreescribiendo CLAUDE.md existente**: el usuario
+  puede tener un CLAUDE.md curado con valor irrecuperable. NUNCA
+  sobreescribir — sugerir refactor.
+- **Templates con `[TBD]` que después fallan auditoría**: los templates
+  generados por `init-user` y `init-project` usan `<!-- pendiente: ... -->`
+  HTML comments en lugar de `[TBD]` para que el auditor no los marque
+  como ERROR placeholders. Comments HTML son ignorados por el regex.
+- **Aplicar el contrato canónico a CLAUDE.md de subdirectorios**: si el
+  proyecto adopta jerarquía (ADR-0007), los CLAUDE.md de subdirectorios
+  pueden NO tener todas las secciones canónicas (porque heredan del root).
+  Por ahora el auditor aplica el contrato uniforme; si el ADR-0007 se
+  acepta, el auditor debe distinguir root vs subdirectorio.
+
+## Señales de alerta
+
+Detente y escala si:
+
+- El usuario pide `init-project` en un directorio que ya tiene CLAUDE.md
+  con >100 líneas de contenido custom (riesgo: pérdida de información)
+- `audit` reporta WARN líneas pero el contenido es legítimamente
+  necesario (ej. listas grandes de comandos sin posibilidad de extracción
+  útil) — sugerir ajustar `SWL_CLAUDEMD_MAX_LINES`, no extraer por extraer
+- El usuario pide `refactor` y propone extracciones que dispersarían
+  contexto crítico (ej. mover "Reglas de máxima prioridad") — rechazar
+  con explicación del anti-patrón