# 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.
