@saulwade/swl-ses 2.2.4 → 2.3.1

package/habilidades/meta-skills-estandar/recursos/convencion-examples.md

@@ -1,93 +1,93 @@
-# Convención `EXAMPLES.md` — recurso opcional para skills críticos
-
-Convención **opcional** para skills cuyo valor depende de ejemplos concretos
-con diff MAL → BIEN. Esta convención NO es retroactiva: las 63 carpetas
-`recursos/` existentes en `habilidades/` no se renombran. Solo aplica a:
-
-- Skills nuevos cuyo dominio se entiende mejor con ejemplos lado a lado.
-- Skills existentes que reciban actualización mayor y agreguen ejemplos.
-
----
-
-## Cuándo aplicarla
-
-Aplicar cuando:
-
-- El skill prescribe **decisiones técnicas** o **patrones** cuyo error es
-  sutil sin un caso concreto (ej: anti-patrones de async, gotchas de framework,
-  decisiones arquitecturales).
-- El skill se beneficia de mostrar 2-4 ejemplos lado a lado: el caso aplicado
-  correctamente vs el caso degenerado.
-- Los ejemplos suman > 100 líneas y meterlos en SKILL.md lo pasaría del
-  límite de 300 líneas.
-
-NO aplicar cuando:
-
-- El skill ya tiene `recursos/` con archivos temáticos específicos
-  (ej: `meta-skills-estandar/recursos/anti-patrones-y-leyes.md`). El nombre
-  temático es más informativo que `EXAMPLES.md`.
-- El skill es un how-to procedural sin antipatrones contrastables.
-- El skill tiene < 80 líneas en SKILL.md y los ejemplos caben en línea.
-
----
-
-## Estructura recomendada
-
-```
-habilidades/<skill-name>/
-├── SKILL.md
-└── recursos/
-    └── EXAMPLES.md
-```
-
-`SKILL.md` enlaza al final con:
-
-```markdown
-Para ejemplos concretos de aplicación, ver [`recursos/EXAMPLES.md`](recursos/EXAMPLES.md).
-```
-
-`EXAMPLES.md` contiene 2-4 ejemplos siguiendo el patrón:
-
-```markdown
-## Ejemplo N — [título corto del escenario]
-
-**Contexto**: [1-2 líneas]
-
-### ❌ Sin <skill-name> (hipotético)
-[código o descripción del enfoque incorrecto + consecuencia observable]
-
-### ✓ Con <skill-name>
-[código o descripción del enfoque correcto + por qué evita la consecuencia]
-```
-
-Cierre de `EXAMPLES.md`: tabla resumen de los ejemplos con la dimensión
-clave que cambió (costo, tiempo, severidad de bug, etc.).
-
----
-
-## Por qué OPCIONAL y no obligatoria
-
-- 63 carpetas `recursos/` ya existen con nomenclatura temática
-  (`anti-patrones-y-leyes.md`, `frameworks-seguridad.md`,
-  `idiomas-framework.md`). Forzar `EXAMPLES.md` rompería información
-  semántica del nombre.
-- La regla core `reglas/skills-estandar.md` ya prescribe que `SKILL.md`
-  no exceda 300 líneas y que los `recursos/` se nombren en kebab-case
-  con sufijo `.md` — esa regla cubre el 95% de los casos.
-- Esta convención **complementa** la regla core para skills donde un nombre
-  semántico genérico (`EXAMPLES.md`) comunica mejor el contenido que un
-  nombre específico (ej: `casos-decisiones-arquitecturales.md` es más largo
-  y menos buscable).
-
----
-
-## Origen
-
-Patrón observado en repos externos analizados el 2026-05-09
-(`temp/agent-skills-main`, `temp/andrej-karpathy-skills-main`):
-varios skills críticos exponen un `EXAMPLES.md` con diffs MAL/BIEN
-auto-cargable como referencia rápida del agente.
-
-Adoptado en `habilidades/doubt-driven-review/recursos/EXAMPLES.md` como
-primera aplicación. Casos futuros: skills de decisiones arquitecturales,
-seguridad, debugging avanzado.
+# Convención `EXAMPLES.md` — recurso opcional para skills críticos
+
+Convención **opcional** para skills cuyo valor depende de ejemplos concretos
+con diff MAL → BIEN. Esta convención NO es retroactiva: las 63 carpetas
+`recursos/` existentes en `habilidades/` no se renombran. Solo aplica a:
+
+- Skills nuevos cuyo dominio se entiende mejor con ejemplos lado a lado.
+- Skills existentes que reciban actualización mayor y agreguen ejemplos.
+
+---
+
+## Cuándo aplicarla
+
+Aplicar cuando:
+
+- El skill prescribe **decisiones técnicas** o **patrones** cuyo error es
+  sutil sin un caso concreto (ej: anti-patrones de async, gotchas de framework,
+  decisiones arquitecturales).
+- El skill se beneficia de mostrar 2-4 ejemplos lado a lado: el caso aplicado
+  correctamente vs el caso degenerado.
+- Los ejemplos suman > 100 líneas y meterlos en SKILL.md lo pasaría del
+  límite de 300 líneas.
+
+NO aplicar cuando:
+
+- El skill ya tiene `recursos/` con archivos temáticos específicos
+  (ej: `meta-skills-estandar/recursos/anti-patrones-y-leyes.md`). El nombre
+  temático es más informativo que `EXAMPLES.md`.
+- El skill es un how-to procedural sin antipatrones contrastables.
+- El skill tiene < 80 líneas en SKILL.md y los ejemplos caben en línea.
+
+---
+
+## Estructura recomendada
+
+```
+habilidades/<skill-name>/
+├── SKILL.md
+└── recursos/
+    └── EXAMPLES.md
+```
+
+`SKILL.md` enlaza al final con:
+
+```markdown
+Para ejemplos concretos de aplicación, ver [`recursos/EXAMPLES.md`](recursos/EXAMPLES.md).
+```
+
+`EXAMPLES.md` contiene 2-4 ejemplos siguiendo el patrón:
+
+```markdown
+## Ejemplo N — [título corto del escenario]
+
+**Contexto**: [1-2 líneas]
+
+### ❌ Sin <skill-name> (hipotético)
+[código o descripción del enfoque incorrecto + consecuencia observable]
+
+### ✓ Con <skill-name>
+[código o descripción del enfoque correcto + por qué evita la consecuencia]
+```
+
+Cierre de `EXAMPLES.md`: tabla resumen de los ejemplos con la dimensión
+clave que cambió (costo, tiempo, severidad de bug, etc.).
+
+---
+
+## Por qué OPCIONAL y no obligatoria
+
+- 63 carpetas `recursos/` ya existen con nomenclatura temática
+  (`anti-patrones-y-leyes.md`, `frameworks-seguridad.md`,
+  `idiomas-framework.md`). Forzar `EXAMPLES.md` rompería información
+  semántica del nombre.
+- La regla core `reglas/skills-estandar.md` ya prescribe que `SKILL.md`
+  no exceda 300 líneas y que los `recursos/` se nombren en kebab-case
+  con sufijo `.md` — esa regla cubre el 95% de los casos.
+- Esta convención **complementa** la regla core para skills donde un nombre
+  semántico genérico (`EXAMPLES.md`) comunica mejor el contenido que un
+  nombre específico (ej: `casos-decisiones-arquitecturales.md` es más largo
+  y menos buscable).
+
+---
+
+## Origen
+
+Patrón observado en repos externos analizados el 2026-05-09
+(`temp/agent-skills-main`, `temp/andrej-karpathy-skills-main`):
+varios skills críticos exponen un `EXAMPLES.md` con diffs MAL/BIEN
+auto-cargable como referencia rápida del agente.
+
+Adoptado en `habilidades/doubt-driven-review/recursos/EXAMPLES.md` como
+primera aplicación. Casos futuros: skills de decisiones arquitecturales,
+seguridad, debugging avanzado.