@saulwade/swl-ses 1.6.0 → 1.6.3

package/habilidades/infra-github-actions/SKILL.md

@@ -1,166 +1,172 @@
----
-name: infra-github-actions
-description: >
-  GitHub Actions CI/CD para proyectos que usan swl-ses. Cubre los tres workflows
-  distribuidos (swl-security.yml, swl-ci.yml, release-please.yml), setup del secret
-  CLAUDE_API_KEY, branch protection y troubleshooting. Cargar cuando se configura
-  CI/CD con GitHub Actions en un proyecto donde está instalado swl-ses.
----
-
-# infra-github-actions — GitHub Actions con swl-ses
-
-## Cuándo cargar
-
-- Al ejecutar `/swl:configurar-ci init` y necesitar guía de setup
-- Al depurar un workflow que no dispara o falla por API key
-- Al configurar branch protection en el proyecto
-- Al decidir si adoptar release-please vs el flujo manual actual
-
-## Cuándo NO cargar
-
-- El proyecto usa Azure DevOps Pipelines o GitLab CI — esos tienen su propia configuración
-- El objetivo es Kubernetes, Terraform o infraestructura cloud (cargar `kubernetes-orquestacion` o `terraform-experto`)
-- La tarea es solo correr tests localmente sin CI
-- El proyecto no usa GitHub como repositorio
-
----
-
-## Workflows distribuidos por swl-ses
-
-| Archivo | Propósito | Secrets requeridos |
-|---------|-----------|-------------------|
-| `swl-security.yml` | Revisión semántica de seguridad con Claude en cada PR | `CLAUDE_API_KEY` |
-| `swl-ci.yml` | Lint + tests en push y PRs. Node 22+24, Python/Rust/Go comentados | Ninguno |
-| `release-please.yml` | Release PR automático + tag + GitHub Release | Ninguno (`GITHUB_TOKEN` automático) |
-
-Instalación con: `/swl:configurar-ci init`
-
----
-
-## Reglas obligatorias
-
-**NUNCA** commitear API keys en código ni en archivos de workflow.
-Todo secret va en GitHub Settings → Secrets and variables → Actions.
-
-**Permisos mínimos siempre**: declarar solo `contents: read` y `pull-requests: write`
-en el nivel del workflow. Nunca `permissions: write-all`.
-
-**Los workflows de forks externos no reciben secrets** por diseño de GitHub.
-La revisión de seguridad con Claude solo funciona en PRs desde ramas del mismo repo,
-no desde repos forked. Es un comportamiento de GitHub, no un bug.
-
-**No hardcodear nombres de rama** más allá de `main`. Si el proyecto usa otra rama
-por defecto, editar el `on: push: branches` en los workflows copiados.
-
----
-
-## Setup de CLAUDE_API_KEY
-
-1. Ir a https://console.anthropic.com y crear o copiar la API key
-2. En GitHub: Settings → Secrets and variables → Actions → New repository secret
-   - Nombre: `CLAUDE_API_KEY`
-   - Valor: la API key
-3. La key necesita permisos tanto para Claude API como para Claude Code
-
-Verificar con gh CLI si el secret ya existe:
-```bash
-gh secret list | grep CLAUDE_API_KEY
-```
-
-Para configurar vía CLI (valor desde stdin, no queda en historial):
-```bash
-gh secret set CLAUDE_API_KEY
-```
-
----
-
-## Branch protection
-
-Aplicar después de tener CI funcionando. El script del repo swl-ses:
-
-```bash
-# Ver qué haría sin aplicar cambios
-node scripts/configurar-branch-protection.js --dry-run
-
-# Aplicar
-node scripts/configurar-branch-protection.js
-```
-
-Requiere `gh` CLI autenticado y permisos de admin en el repositorio.
-
-Configura: require PR, status checks (`test (22)`, `test (24)`, `smoke`),
-1 approval, bloquea force-push y deletions.
-
----
-
-## Adoptar release-please (opt-in)
-
-Ver `docs/RELEASE-PLEASE-MIGRATION.md` para comparativa completa.
-
-El flujo actual del repo swl-ses usa `scripts/publicar.js` (manual). release-please
-es una alternativa automática viable para proyectos de usuarios.
-
-Instalar:
-```
-/swl:configurar-ci --with-release-please
-```
-
-Una vez activo, el flujo es:
-1. Hacer merge de commits convencionales a main
-2. release-please abre un "Release PR" automático con bump de versión y CHANGELOG
-3. Al mergear ese PR → tag git + GitHub Release creado automáticamente
-
----
-
-## Gotchas / Errores comunes no obvios
-
-**GitHub Free + repo privado → 403 en branch protection Y Rulesets**: tanto el endpoint legacy
-`/repos/.../branches/{}/protection` como el endpoint moderno `/repos/.../rulesets` requieren
-**plan de pago** en repos privados (HTTP 403 "Upgrade to GitHub Pro or make this repository public"
-en ambos). Mi documentación inicial afirmó incorrectamente que Rulesets era gratis para repos
-privados Free — verificación empírica posterior confirmó que NO. Ambos endpoints están bloqueados.
-
-Planes que destraban la feature en privado:
-- **Pro** ($4/mes): aplica a repos en cuenta personal del titular Pro.
-- **Team** ($4/usuario/mes): aplica solo a repos **de la organización** que paga Team. NO aplica
-  a repos en la cuenta personal del admin de la org. Para que Team aplique al repo, transferirlo:
-  `gh repo transfer cuenta-personal/repo --new-owner org`.
-
-Sin plan de pago y manteniendo repo privado, las opciones son: pre-push hook local
-(bypasseable con `--no-verify`) y workflow advisory (no bloquea push, crea issue post-hoc).
-
-**Push directo a main bloqueado tras activar branch protection**: si configuraste
-branch protection antes de que tu usuario tuviera al menos un PR mergeado con los
-status checks pasando, el repo puede quedar en estado donde nadie puede mergear.
-Causa: GitHub verifica los status checks declarados antes de permitir el merge; si
-los checks no han corrido en el branch, el botón de merge queda bloqueado.
-Fix: crear una rama temporal con un cambio trivial, abrir PR, dejar que los checks
-corran, y mergear. Luego ya funciona el flujo normal.
-
-**GITHUB_TOKEN no puede aprobar su propio PR** al usar release-please: release-please
-crea un Release PR con el GITHUB_TOKEN del bot — ese mismo token no puede aprobarlo
-si el repo requiere al menos 1 approval humano. Causa: GitHub bloquea la auto-aprobación
-con el token de Actions por defecto.
-Fix: crear un Personal Access Token (PAT) con scope `repo` y usarlo en el workflow:
-`token: ${{ secrets.MY_RELEASE_TOKEN }}`. O reducir el required approvals a 0 para
-el Release PR (no recomendado en repos con múltiples contribuidores).
-
-**`anthropics/claude-code-security-review@main` falla con "API key not set"**: el
-secret `CLAUDE_API_KEY` no está configurado o el nombre no coincide exactamente.
-La action es sensible a mayúsculas — `claude_api_key` (minúsculas) no funciona.
-Fix: verificar con `gh secret list`. El nombre debe ser exactamente `CLAUDE_API_KEY`.
-
-**El workflow `swl-ci.yml` pasa localmente pero falla en CI con "lint script not found"**:
-el campo `lint` no está definido en `package.json` del proyecto del usuario. La plantilla
-usa `npm run lint --if-present` precisamente para ser tolerante, pero si el proyecto
-tiene un nombre distinto (ej: `eslint`, `check`) el step se salta silenciosamente.
-Fix: agregar el script `"lint": "..."` en `package.json` o editar el workflow para usar
-el nombre correcto.
-
-**release-please genera changelog con commits `chore(release)` del repo padre swl-ses**:
-si el proyecto del usuario adoptó los mensajes de commit de swl-ses que incluyen
-`chore(release): v5.X.Y`, release-please los interpreta como commits de release
-y puede generar bumps incorrectos.
-Fix: usar mensajes de commit convencionales estándar para el proyecto del usuario,
-separados del estilo de swl-ses. Los prefijos `feat:`, `fix:`, `chore:` sin el
-patrón `(release): vX.Y.Z` no causan conflicto.
+---
+name: infra-github-actions
+description: >
+  GitHub Actions CI/CD para proyectos que usan swl-ses. Cubre los tres workflows
+  distribuidos (swl-security.yml, swl-ci.yml, release-please.yml), setup del secret
+  CLAUDE_API_KEY, branch protection y troubleshooting. Cargar cuando se configura
+  CI/CD con GitHub Actions en un proyecto donde está instalado swl-ses.
+version: "1.0.0"
+exclusiones:
+  - "No cargar para otros sistemas CI/CD (GitLab CI, CircleCI, Jenkins) — este skill cubre solo GitHub Actions; para GitLab usar el workflow YAML estándar de GitLab."
+  - "No cargar para configuración de pipelines internos del repo swl-ses — esos están en .github/workflows/ y no son distribuibles a usuarios."
+  - "No cargar para troubleshooting de runners self-hosted — este skill asume GitHub-hosted runners; runners propios requieren guía aparte."
+  - "No cargar para definir nuevos workflows desde cero sin relación con swl-security/swl-ci/release-please — para workflows custom usar la documentación oficial de GitHub Actions."
+---
+
+# infra-github-actions — GitHub Actions con swl-ses
+
+## Cuándo cargar
+
+- Al ejecutar `/swl:configurar-ci init` y necesitar guía de setup
+- Al depurar un workflow que no dispara o falla por API key
+- Al configurar branch protection en el proyecto
+- Al decidir si adoptar release-please vs el flujo manual actual
+
+## Cuándo NO cargar
+
+- El proyecto usa Azure DevOps Pipelines o GitLab CI — esos tienen su propia configuración
+- El objetivo es Kubernetes, Terraform o infraestructura cloud (cargar `kubernetes-orquestacion` o `terraform-experto`)
+- La tarea es solo correr tests localmente sin CI
+- El proyecto no usa GitHub como repositorio
+
+---
+
+## Workflows distribuidos por swl-ses
+
+| Archivo | Propósito | Secrets requeridos |
+|---------|-----------|-------------------|
+| `swl-security.yml` | Revisión semántica de seguridad con Claude en cada PR | `CLAUDE_API_KEY` |
+| `swl-ci.yml` | Lint + tests en push y PRs. Node 22+24, Python/Rust/Go comentados | Ninguno |
+| `release-please.yml` | Release PR automático + tag + GitHub Release | Ninguno (`GITHUB_TOKEN` automático) |
+
+Instalación con: `/swl:configurar-ci init`
+
+---
+
+## Reglas obligatorias
+
+**NUNCA** commitear API keys en código ni en archivos de workflow.
+Todo secret va en GitHub Settings → Secrets and variables → Actions.
+
+**Permisos mínimos siempre**: declarar solo `contents: read` y `pull-requests: write`
+en el nivel del workflow. Nunca `permissions: write-all`.
+
+**Los workflows de forks externos no reciben secrets** por diseño de GitHub.
+La revisión de seguridad con Claude solo funciona en PRs desde ramas del mismo repo,
+no desde repos forked. Es un comportamiento de GitHub, no un bug.
+
+**No hardcodear nombres de rama** más allá de `main`. Si el proyecto usa otra rama
+por defecto, editar el `on: push: branches` en los workflows copiados.
+
+---
+
+## Setup de CLAUDE_API_KEY
+
+1. Ir a https://console.anthropic.com y crear o copiar la API key
+2. En GitHub: Settings → Secrets and variables → Actions → New repository secret
+   - Nombre: `CLAUDE_API_KEY`
+   - Valor: la API key
+3. La key necesita permisos tanto para Claude API como para Claude Code
+
+Verificar con gh CLI si el secret ya existe:
+```bash
+gh secret list | grep CLAUDE_API_KEY
+```
+
+Para configurar vía CLI (valor desde stdin, no queda en historial):
+```bash
+gh secret set CLAUDE_API_KEY
+```
+
+---
+
+## Branch protection
+
+Aplicar después de tener CI funcionando. El script del repo swl-ses:
+
+```bash
+# Ver qué haría sin aplicar cambios
+node scripts/configurar-branch-protection.js --dry-run
+
+# Aplicar
+node scripts/configurar-branch-protection.js
+```
+
+Requiere `gh` CLI autenticado y permisos de admin en el repositorio.
+
+Configura: require PR, status checks (`test (22)`, `test (24)`, `smoke`),
+1 approval, bloquea force-push y deletions.
+
+---
+
+## Adoptar release-please (opt-in)
+
+Ver `docs/RELEASE-PLEASE-MIGRATION.md` para comparativa completa.
+
+El flujo actual del repo swl-ses usa `scripts/publicar.js` (manual). release-please
+es una alternativa automática viable para proyectos de usuarios.
+
+Instalar:
+```
+/swl:configurar-ci --with-release-please
+```
+
+Una vez activo, el flujo es:
+1. Hacer merge de commits convencionales a main
+2. release-please abre un "Release PR" automático con bump de versión y CHANGELOG
+3. Al mergear ese PR → tag git + GitHub Release creado automáticamente
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+**GitHub Free + repo privado → 403 en branch protection Y Rulesets**: tanto el endpoint legacy
+`/repos/.../branches/{}/protection` como el endpoint moderno `/repos/.../rulesets` requieren
+**plan de pago** en repos privados (HTTP 403 "Upgrade to GitHub Pro or make this repository public"
+en ambos). Mi documentación inicial afirmó incorrectamente que Rulesets era gratis para repos
+privados Free — verificación empírica posterior confirmó que NO. Ambos endpoints están bloqueados.
+
+Planes que destraban la feature en privado:
+- **Pro** ($4/mes): aplica a repos en cuenta personal del titular Pro.
+- **Team** ($4/usuario/mes): aplica solo a repos **de la organización** que paga Team. NO aplica
+  a repos en la cuenta personal del admin de la org. Para que Team aplique al repo, transferirlo:
+  `gh repo transfer cuenta-personal/repo --new-owner org`.
+
+Sin plan de pago y manteniendo repo privado, las opciones son: pre-push hook local
+(bypasseable con `--no-verify`) y workflow advisory (no bloquea push, crea issue post-hoc).
+
+**Push directo a main bloqueado tras activar branch protection**: si configuraste
+branch protection antes de que tu usuario tuviera al menos un PR mergeado con los
+status checks pasando, el repo puede quedar en estado donde nadie puede mergear.
+Causa: GitHub verifica los status checks declarados antes de permitir el merge; si
+los checks no han corrido en el branch, el botón de merge queda bloqueado.
+Fix: crear una rama temporal con un cambio trivial, abrir PR, dejar que los checks
+corran, y mergear. Luego ya funciona el flujo normal.
+
+**GITHUB_TOKEN no puede aprobar su propio PR** al usar release-please: release-please
+crea un Release PR con el GITHUB_TOKEN del bot — ese mismo token no puede aprobarlo
+si el repo requiere al menos 1 approval humano. Causa: GitHub bloquea la auto-aprobación
+con el token de Actions por defecto.
+Fix: crear un Personal Access Token (PAT) con scope `repo` y usarlo en el workflow:
+`token: ${{ secrets.MY_RELEASE_TOKEN }}`. O reducir el required approvals a 0 para
+el Release PR (no recomendado en repos con múltiples contribuidores).
+
+**`anthropics/claude-code-security-review@main` falla con "API key not set"**: el
+secret `CLAUDE_API_KEY` no está configurado o el nombre no coincide exactamente.
+La action es sensible a mayúsculas — `claude_api_key` (minúsculas) no funciona.
+Fix: verificar con `gh secret list`. El nombre debe ser exactamente `CLAUDE_API_KEY`.
+
+**El workflow `swl-ci.yml` pasa localmente pero falla en CI con "lint script not found"**:
+el campo `lint` no está definido en `package.json` del proyecto del usuario. La plantilla
+usa `npm run lint --if-present` precisamente para ser tolerante, pero si el proyecto
+tiene un nombre distinto (ej: `eslint`, `check`) el step se salta silenciosamente.
+Fix: agregar el script `"lint": "..."` en `package.json` o editar el workflow para usar
+el nombre correcto.
+
+**release-please genera changelog con commits `chore(release)` del repo padre swl-ses**:
+si el proyecto del usuario adoptó los mensajes de commit de swl-ses que incluyen
+`chore(release): v5.X.Y`, release-please los interpreta como commits de release
+y puede generar bumps incorrectos.
+Fix: usar mensajes de commit convencionales estándar para el proyecto del usuario,
+separados del estilo de swl-ses. Los prefijos `feat:`, `fix:`, `chore:` sin el
+patrón `(release): vX.Y.Z` no causan conflicto.

package/habilidades/meta-skills-estandar/SKILL.md

@@ -272,6 +272,12 @@ el contenido específico, sin inflar el contexto con cada invocación:
   valor depende de mostrar diff MAL→BIEN lado a lado (decisiones, arquitectura,
   anti-patrones sutiles). NO retroactiva — las 63 carpetas `recursos/` existentes
   no se renombran. Ver [recursos/convencion-examples.md](recursos/convencion-examples.md).
+- **Rúbrica skill-judge (Knowledge Delta + Freedom Calibration + 5 patrones)** —
+  tres lentes complementarios a las 10 dimensiones de `/swl:evaluar-skill`
+  para autoría: detectar contenido redundante, matchear libertad a fragilidad,
+  elegir patrón estructural al inicio. NO reemplaza el gate `/swl:evaluar-skill`;
+  aplica durante la escritura. Ver [recursos/skill-judge-rubrica.md](recursos/skill-judge-rubrica.md).
+  Origen: ADR-0024.
 
 Cada recurso tiene ToC al inicio y es autocontenido — leer solo el relevante
 al caso en cuestión en lugar de los tres.

package/habilidades/meta-skills-estandar/recursos/skill-judge-rubrica.md

@@ -0,0 +1,281 @@
+# Rúbrica skill-judge — 3 dimensiones complementarias a `evaluar-skill`
+
+Recurso opcional que se carga bajo demanda cuando se autora un SKILL.md y se
+quieren aplicar tres lentes adicionales que el comando `/swl:evaluar-skill`
+no mide directamente. Adaptación de la rúbrica `skill-judge` (agent-toolkit,
+8 dimensiones × 120 puntos) para complementar las 10 dimensiones ponderadas
+del comando SWL.
+
+**Origen**: análisis comparativo documentado en ADR-0024 — Opción B.
+**NO reemplaza** `/swl:evaluar-skill`; añade tres lentes de autoría que el
+comando deja fuera por ser difíciles de medir programáticamente.
+
+---
+
+## Por qué este recurso existe
+
+El comando `/swl:evaluar-skill` mide 10 dimensiones que cubren bien:
+trigger, orquestación, scope, progressive disclosure, robustez, completitud
+estructural. Tras comparar con la rúbrica de 8 dimensiones de
+`temp/agent-toolkit/skills/skill-judge/`, detecté tres lentes que aporta
+valor agregado al **autor del skill**, no al evaluador automático:
+
+| Lente skill-judge | Por qué falta en SWL | Cuándo aporta |
+|---|---|---|
+| **Knowledge Delta** | Difícil de medir programáticamente | Al escribir skill nuevo: detectar contenido redundante |
+| **Freedom Calibration** | Subjetivo (alta/media/baja libertad) | Al elegir nivel de prescripción según fragilidad |
+| **Pattern Recognition (5 patrones)** | Clasificación, no calidad | Al elegir estructura del skill al inicio |
+
+Estas tres dimensiones se aplican durante la **autoría**, no la **evaluación
+final**. Para el gate de calidad sigue usándose `/swl:evaluar-skill`.
+
+---
+
+## Lente 1 — Knowledge Delta
+
+> **Buen Skill = Conocimiento de experto − lo que el modelo ya sabe.**
+
+El valor de un skill se mide por su **delta de conocimiento** — la brecha
+entre lo que provee y lo que el modelo ya tiene en sus pesos.
+
+### Las 3 categorías de contenido
+
+| Tipo | Definición | Tratamiento |
+|------|-----------|-------------|
+| **Expert** | El modelo genuinamente no lo sabe | Mantener — es el valor del skill |
+| **Activation** | El modelo lo sabe pero podría no pensar en ello | Mantener si es breve — funciona como recordatorio |
+| **Redundant** | El modelo definitivamente lo sabe | Borrar — desperdicia tokens |
+
+### Red flags (contenido a borrar agresivamente)
+
+- "¿Qué es [concepto básico]?" — el modelo lo sabe.
+- Tutoriales paso a paso para operaciones estándar (open file, read, write).
+- Explicaciones de uso de librerías comunes (cómo usar `requests`,
+  `fetch`, etc.).
+- Best practices genéricas ("escribe código limpio", "maneja errores").
+- Definiciones de términos estándar de la industria.
+
+### Green flags (contenido de alto valor)
+
+- Decision trees para decisiones no obvias ("cuando X falla, intenta Y
+  porque Z").
+- Trade-offs que solo un experto conoce ("A es más rápido pero B maneja
+  el edge case C").
+- Edge cases de experiencia real ("MissingGreenlet pasa cuando…").
+- "NEVER hagas X porque [razón no obvia]".
+- Frameworks de pensamiento específicos del dominio.
+
+### Test mental
+
+Al revisar cada sección de tu SKILL.md, preguntar:
+
+1. *¿El modelo ya sabe esto?* Si sí → marcar como Redundant, borrar.
+2. *¿Esto explica TO el modelo o FOR el modelo?* TO = redundant; FOR = valor.
+3. Calcular ratio E:A:R. Bueno: >70% Expert, <20% Activation, <10% Redundant.
+
+### Conexión con `reducir-entropia`
+
+El skill SWL `reducir-entropia` aplica el mismo principio al codebase
+(menos líneas finales = win). Knowledge delta lo aplica al SKILL.md
+(menos tokens redundantes = win). Mismo lente, distinto target.
+
+---
+
+## Lente 2 — Freedom Calibration
+
+> **Match freedom to fragility.**
+
+Diferentes tareas requieren diferentes niveles de restricción en el skill.
+
+### El espectro
+
+| Tipo de tarea | Debería tener | Por qué |
+|---|---|---|
+| Creativo / Diseño | Alta libertad | Múltiples caminos válidos; diferenciación es el valor |
+| Code review | Libertad media | Hay principios, pero juicio requerido |
+| Operaciones en formato de archivo | Baja libertad | Un byte mal corrompe el archivo |
+
+### Ejemplos
+
+**Alta libertad** (principios, no pasos):
+
+```markdown
+Commit a una dirección estética BOLD. Elige un extremo: minimalismo
+brutal, caos maximalista, retro-futurista, orgánico natural…
+```
+
+**Libertad media** (priorización + criterio):
+
+```markdown
+Prioridad de revisión:
+1. Vulnerabilidades de seguridad (must fix)
+2. Errores de lógica (must fix)
+3. Performance (should fix)
+4. Mantenibilidad (opcional)
+```
+
+**Baja libertad** (script exacto):
+
+```markdown
+**OBLIGATORIO**: usar exactamente `scripts/create-doc.py` con parámetros
+`--title "X" --author "Y"`. NO modificar el script.
+```
+
+### Test
+
+Pregunta: *si el modelo comete error, ¿cuál es la consecuencia?*
+
+- Consecuencia alta → libertad baja (prescriptivo).
+- Consecuencia baja → libertad alta (principios).
+
+### Errores comunes de calibración
+
+- **Rígido para tarea creativa**: skill que prescribe paso a paso una
+  decisión estética destruye el valor del skill.
+- **Vago para operación frágil**: skill que dice "ten cuidado al editar
+  XML" sin reglas exactas garantiza archivos corruptos.
+
+---
+
+## Lente 3 — Patrones reconocibles (5 patrones del agent-toolkit)
+
+Al elegir la **estructura** de un skill nuevo, identificar a cuál de
+estos 5 patrones se ajusta. Ayuda a calibrar tamaño y profundidad.
+
+| Patrón | Líneas | Características clave | Cuándo usarlo |
+|---|---|---|---|
+| **Mindset** | ~50 | Pensamiento > técnica, NEVER list fuerte, alta libertad | Tareas creativas que requieren gusto |
+| **Navigation** | ~30 | SKILL.md mínimo, rutea a sub-archivos en `recursos/` | Múltiples escenarios distintos |
+| **Philosophy** | ~150 | Dos pasos: Filosofía → Express, enfatiza craft | Arte/creación que requiere originalidad |
+| **Process** | ~200 | Workflow por fases, checkpoints, libertad media | Proyectos multi-paso complejos |
+| **Tool** | ~300 | Decision trees, ejemplos de código, libertad baja | Operaciones precisas en formato específico |
+
+### Guía de selección
+
+| Tu tarea es… | Patrón recomendado |
+|---|---|
+| Requiere gusto y creatividad | Mindset (~50 líneas) |
+| Requiere originalidad y craft quality | Philosophy (~150 líneas) |
+| Tiene múltiples sub-escenarios distintos | Navigation (~30 líneas) |
+| Proyecto complejo multi-paso | Process (~200 líneas) |
+| Operación precisa en formato específico | Tool (~300 líneas) |
+
+### Mapeo a skills SWL existentes (referencia)
+
+- `meta-skills-estandar` — Philosophy/Process (526 líneas; rebasa el ideal
+  pero contiene 5 secciones extendidas justificadas por ADR).
+- `tdd-workflow` — Process.
+- `verificar-trabajo` — Process con decision trees.
+- `discutir-fase` — Process.
+- `reducir-entropia` — Mindset (~200 líneas, anti-patrón consciente).
+- `proceso-confianza-pre-implementacion` — Process.
+- `proceso-autoverificacion-evidencias` — Process.
+- `aprender-de-git-diff` — Mindset/Process híbrido.
+- Skills de formato de archivo (cuando aplique) — Tool.
+
+---
+
+## Las 7 fallas comunes (Common Failure Patterns)
+
+Adaptado de skill-judge "Common Failure Patterns". Si tu skill cae en uno
+de estos, refactorizar antes de mergear.
+
+### 1. The Tutorial
+
+**Síntoma**: explica qué es PDF, cómo funciona Python, uso básico de librería.
+**Causa**: autor asume que el skill debe "enseñar" al modelo.
+**Fix**: el modelo ya sabe esto. Borrar todas las explicaciones básicas.
+Enfocar en decisiones de experto, trade-offs, anti-patrones.
+
+### 2. The Dump
+
+**Síntoma**: SKILL.md de 800+ líneas con todo incluido.
+**Causa**: sin diseño de progressive disclosure.
+**Fix**: routing y decision trees en SKILL.md (<300 líneas ideal). Contenido
+detallado a `recursos/`, cargado bajo demanda.
+
+### 3. The Orphan References
+
+**Síntoma**: directorio `recursos/` existe pero los archivos nunca se cargan.
+**Causa**: sin triggers explícitos de carga.
+**Fix**: agregar "OBLIGATORIO — LEER ARCHIVO COMPLETO" en puntos de
+decisión del workflow. Agregar "NO cargar" para prevenir sobre-carga.
+
+### 4. The Checkbox Procedure
+
+**Síntoma**: Paso 1, Paso 2, Paso 3… procedimientos mecánicos.
+**Causa**: autor piensa en procedimientos, no en frameworks de pensamiento.
+**Fix**: transformar en "Antes de hacer X, pregúntate…". Enfocar en
+principios de decisión, no secuencias de operación.
+
+### 5. The Vague Warning
+
+**Síntoma**: "Ten cuidado", "evita errores", "considera edge cases".
+**Causa**: autor sabe que cosas pueden salir mal pero no las articuló.
+**Fix**: NEVER list específico con ejemplos concretos y razones no obvias.
+"NEVER uses X porque [problema específico que solo experiencia enseña]".
+
+### 6. The Invisible Skill
+
+**Síntoma**: gran contenido pero el skill raramente se activa.
+**Causa**: description vaga, sin keywords, sin trigger scenarios.
+**Fix**: description responde WHAT + WHEN + KEYWORDS. "Usar cuando…" +
+escenarios específicos + términos buscables.
+
+### 7. The Over-Engineered
+
+**Síntoma**: README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, CONTRIBUTING.md
+dentro del directorio del skill.
+**Causa**: tratar al skill como proyecto de software.
+**Fix**: borrar todos los archivos auxiliares. Solo incluir lo que el
+modelo necesita para la tarea. Cero documentación sobre el skill mismo.
+
+---
+
+## NUNCA al evaluar (skill-judge)
+
+- **NUNCA** dar score alto solo porque "se ve profesional" o bien formateado.
+- **NUNCA** ignorar token waste — cada párrafo redundante penaliza.
+- **NUNCA** dejar que la longitud te impresione — un skill de 43 líneas
+  puede superar a uno de 500.
+- **NUNCA** saltarse el test mental de los decision trees — ¿realmente
+  llevan a la elección correcta?
+- **NUNCA** perdonar explicaciones básicas con "pero da contexto útil".
+- **NUNCA** subvalorar el campo `description` — pobre description = skill
+  nunca se activa.
+
+---
+
+## La pregunta meta
+
+Al revisar cualquier skill, regresar a:
+
+> **"¿Un experto en este dominio, mirando este skill, diría: 'sí, esto
+> captura conocimiento que me tomó años aprender'?"**
+
+Si la respuesta es sí → valor genuino.
+Si la respuesta es no → comprime lo que el modelo ya sabe → basura.
+
+Los mejores skills son **cerebros expertos comprimidos** — toman 10 años
+de acumulación de un diseñador y los comprimen en 43 líneas, o la
+experiencia operacional de un experto en documentos en un decision tree
+de 200 líneas.
+
+Lo que se comprime debe ser cosas que el modelo NO tiene. De lo contrario,
+es compresión basura.
+
+---
+
+## Cómo aplicar este recurso durante autoría
+
+1. **Antes de escribir**: identificar patrón (Mindset/Navigation/Philosophy/
+   Process/Tool) según la tabla de selección. Esto define tamaño objetivo.
+2. **Durante escritura**: aplicar Freedom Calibration — match libertad a
+   fragilidad.
+3. **Después de primera versión**: pasar el lente de Knowledge Delta sección
+   por sección. Marcar E/A/R. Borrar Redundant agresivamente.
+4. **Antes de commit**: revisar contra las 7 fallas comunes.
+5. **Antes de merge**: ejecutar `/swl:evaluar-skill <nombre>` para el score
+   formal de las 10 dimensiones SWL.
+
+Los 3 lentes de este recurso son aditivos al gate formal. No lo reemplazan.