claude-code-arcane 2.1.0 → 2.3.0

package/skills/music-composition/references/harmony.md

@@ -0,0 +1,82 @@
+# Armonía
+
+## Armonía funcional
+
+Tres funciones, y todo lo demás es sustitución o adorno:
+
+| Función | Grados (mayor) | Efecto |
+|---|---|---|
+| **Tónica** | I, vi, iii | Reposo, llegada |
+| **Subdominante** | IV, ii | Salida, preparación |
+| **Dominante** | V, vii° | Tensión, exige resolución |
+
+El movimiento fuerte es subdominante → dominante → tónica. Todo lo demás es demorar, sustituir o negar esa expectativa.
+
+**Ritmo armónico** — la velocidad de cambio de acorde es una palanca independiente de la progresión. La misma secuencia a un acorde por compás vs dos por compás cambia la urgencia sin cambiar una nota.
+
+## Cadencias
+
+| Cadencia | Movimiento | Efecto |
+|---|---|---|
+| Auténtica perfecta | V → I, con tónica en soprano y bajo | Cierre total |
+| Auténtica imperfecta | V → I invertido o sin tónica arriba | Cierre débil, sigue |
+| Plagal | IV → I | Reposo sin tensión previa; sabor modal/himno |
+| Semicadencia | → V | Pausa abierta, pregunta |
+| Rota | V → vi | Sorpresa, evita el cierre esperado |
+| Suspendida (picardía inversa) | resolución a menor donde se esperaba mayor | Ensombrece |
+
+## Armonía modal
+
+Cuando la progresión no quiere funcionalidad, el modo aporta color por su grado característico:
+
+| Modo | Grado característico | Carácter |
+|---|---|---|
+| Jónico | — | Neutro, brillante |
+| Dórico | ♮6 (sobre menor) | Menor sin tragedia; folk, aventura |
+| Frigio | ♭2 | Tensión oscura, MENA/flamenco |
+| Lidio | ♯4 | Suspensión luminosa, asombro |
+| Mixolidio | ♭7 | Rock/folk, menos gravedad que jónico |
+| Eólico | ♭6 natural | Menor estándar |
+| Locrio | ♭2 y ♭5 | Inestable, casi inusable como centro |
+
+En modal, evitar el V mayor: reintroduce función dominante y colapsa el modo a mayor/menor.
+
+## Armonía cromática
+
+- **Acordes prestados** — tomar del menor paralelo en un contexto mayor (♭VI, ♭VII, iv). Ensombrece sin modular
+- **Dominantes secundarias** — V/x tonicaliza cualquier grado. `C - E7 - Am` hace de Am un centro momentáneo
+- **Sustitución tritonal** — reemplazar V7 por el ♭II7. `G7 → D♭7` antes de C: mismo tritono, bajo cromático
+- **Napolitana (♭II)** — color dramático de aproximación a la dominante
+- **Acordes de sexta aumentada** — resolución cromática doble hacia V, muy tensa
+
+## Modulación
+
+De más suave a más abrupta:
+
+1. **Directa a tonalidad cercana** (relativo, dominante, subdominante): casi imperceptible
+2. **Por pivote** — un acorde común a las dos tonalidades reinterpretado. La técnica más limpia
+3. **Por dominante secundaria** — introducir el V de la nueva tonalidad
+4. **Cromática por bajo** — mover el bajo por semitonos hasta el nuevo centro
+5. **Enarmónica** — reinterpretar un acorde ambiguo (disminuido, sexta aumentada) hacia otro lado
+6. **Truncada / directa lejana** — cortar y arrancar en la nueva tonalidad. Efecto de corte cinematográfico
+
+Para juegos, la modulación por pivote es la única que sobrevive a un cambio de estado en tiempo real sin sonar a error.
+
+## Voice leading
+
+- Mover cada voz lo mínimo posible; la conducción suave es lo que hace que una progresión "funcione"
+- Resolver las tensiones: 7ª baja por grado, 4ª suspendida baja a 3ª
+- Evitar 5ªs y 8ªs paralelas entre voces exteriores en contexto tonal tradicional (en pop/rock son idiomáticas)
+- Evitar el salto de la voz más aguda junto con el bajo en la misma dirección al llegar a una cadencia
+- Doblar la tónica antes que la 5ª, y la 5ª antes que la 3ª
+
+## Reharmonización
+
+Palancas, de menor a mayor impacto:
+
+1. Cambiar inversiones — mismo acorde, bajo distinto
+2. Agregar extensiones (7, 9, 11, 13) — color sin cambiar función
+3. Sustituir por función equivalente — I → vi, V → iii
+4. Insertar dominantes secundarias entre acordes existentes
+5. Cambiar el modo del acorde — mayor por menor
+6. Reemplazar la progresión entera manteniendo la melodía: cada nota melódica admite varios acordes

package/skills/music-composition/references/melody.md

@@ -0,0 +1,48 @@
+# Melodía
+
+## Qué hace que una melodía se pegue
+
+Cuatro propiedades, y ninguna es "ser linda":
+
+1. **Perfil reconocible** — la silueta (sube, se sostiene, cae) es identificable sin el ritmo
+2. **Un gesto memorable** — un salto, una nota fuera de la escala, una síncopa. Un solo evento distintivo, no cinco
+3. **Repetición con variación** — el oído necesita reconocer antes de que le interese lo nuevo
+4. **Relación clara con la armonía** — las notas fuertes caen en tiempos fuertes y son consonantes o tensiones que resuelven
+
+Si una melodía no se pega, casi siempre falta el punto 2: es fluida, correcta y sin ningún evento que el oído pueda agarrar.
+
+## Construcción
+
+**Grados de escala, no notas.** Escribir `5 - 3 - 2 - 1` en vez de `G - E - D - C` la hace portable y expone la estructura.
+
+**Balance salto/grado.** Melodía toda por grados conjuntos: suave y anodina. Toda por saltos: instrumental, difícil de cantar. La proporción típica en música vocal memorable es mayoría de grados con 1-2 saltos ubicados en el punto de mayor interés.
+
+**Clímax único.** La nota más aguda debería aparecer una vez, y tarde. Si el punto alto llega en el compás 2, no queda a dónde ir.
+
+**Registro como recurso finito.** Cada octava que subís es un recurso que se gasta. Guardá el registro alto para el momento que lo necesita.
+
+## Desarrollo motívico
+
+Un motivo es una célula de 2-5 notas. Las transformaciones, de más a menos reconocible:
+
+| Transformación | Qué hace |
+|---|---|
+| **Repetición literal** | Establece |
+| **Secuencia** | Mismo motivo, otra altura. La herramienta más eficiente |
+| **Transposición diatónica** | Igual pero adaptado a la escala; cambia intervalos |
+| **Inversión** | Espeja los intervalos. Mismo ADN, otro carácter |
+| **Retrogradación** | Al revés. Reconocible solo si el motivo es rítmicamente distintivo |
+| **Aumentación / disminución** | Duplicar o dividir las duraciones. Aumentación = épico; disminución = urgencia |
+| **Fragmentación** | Quedarse con un trozo y repetirlo. Genera desarrollo/tensión |
+| **Ornamentación** | Rellenar con notas de paso. Cuidado: diluye |
+
+En música de juego, la aumentación y la fragmentación de un mismo motivo son la forma más barata de tener 4 variantes de un tema con una sola idea.
+
+## Estructura de frase
+
+- **Antecedente / consecuente** — 4+4 compases: la primera termina abierta (semicadencia), la segunda cierra. El patrón de pregunta-respuesta más usado
+- **Sentence** — presentación (2), continuación con fragmentación (2), cadencia (4)
+- **Frases asimétricas** (3, 5, 7 compases) — inquietan, útiles para tensión
+- **Elisión** — la última nota de una frase es la primera de la siguiente. Elimina la respiración, encadena
+
+**Prosodia (si hay letra):** las sílabas acentuadas caen en tiempos fuertes y en notas largas. Una melodía que pelea con el acento natural de la palabra suena mal aunque la armonía sea perfecta. Las vocales abiertas soportan notas agudas y largas; las cerradas no.

package/skills/music-composition/references/orchestration.md

@@ -0,0 +1,69 @@
+# Orquestación
+
+## Rangos y carácter
+
+Rangos prácticos (no extremos virtuosos). El **carácter cambia por registro** en el mismo instrumento — es lo que más se ignora.
+
+| Instrumento | Rango práctico | Registro grave | Registro agudo |
+|---|---|---|---|
+| Flauta | C4 – C7 | Aireado, débil, se tapa | Brillante, penetrante |
+| Clarinete | D3 – C6 | Oscuro, cálido, único | Estridente si se fuerza |
+| Oboe | B♭3 – G6 | Nasal, presente | Tenso |
+| Fagot | B♭1 – E5 | Sombrío, cómico | Vulnerable, expresivo |
+| Corno | F2 – F5 | Noble, difuso | Heroico, esfuerzo audible |
+| Trompeta | E3 – C6 | Sólido | Brillante, corta cualquier textura |
+| Trombón | E2 – F4 | Grave, potente | Cantabile |
+| Violín | G3 – E7 | Cálido (cuerda G) | Brillante; muy agudo = tensión |
+| Viola | C3 – E6 | Ronco, melancólico | Delgado |
+| Cello | C2 – C6 | Profundo | El registro más expresivo de la orquesta |
+| Contrabajo | E1 – G4 | Fundamento | Raro, tenso |
+| Voz (soprano) | C4 – A5 | Débil | Potente, esfuerzo audible |
+| Voz (barítono) | A2 – F4 | Cómodo | Intenso |
+
+## Densidad de arreglo
+
+**La regla que resuelve el 80% de los problemas: menos elementos, mejor definidos.**
+
+| Nivel | Elementos simultáneos | Uso |
+|---|---|---|
+| Íntimo | 1-2 | Momentos de máxima atención |
+| Cámara | 3-5 | Estándar de gameplay sostenido |
+| Pleno | 6-10 | Clímax |
+| Tutti | todo | Una vez, y corto |
+
+En música de juego, el nivel de densidad es la palanca adaptativa más eficiente: subir y bajar capas sin cambiar el material.
+
+## Voicing y textura
+
+- **Espaciado natural** — intervalos amplios abajo, cerrados arriba. Copia la serie armónica; suena limpio automáticamente
+- **No apilar en el mismo registro** — cuatro instrumentos entre C4 y C5 producen barro. Separar por octavas
+- **Doblar con intención** — al unísono para peso, a la octava para brillo, en 3ªs/6ªs para dulzura. Doblar todo es no doblar nada
+- **Registro medio saturado** — 500 Hz-2 kHz es donde vive el diálogo. En un juego, la música debería *dejar ese rango relativamente libre* si hay VO simultáneo (ver `/audio-mix`)
+
+## Combinaciones que funcionan
+
+| Combinación | Efecto |
+|---|---|
+| Cello + corno (unísono) | Calidez con peso |
+| Clarinete grave + viola | Oscuridad ambigua |
+| Flauta + violín (octava) | Brillo aireado |
+| Pizzicato + arpa/mallets | Puntillismo, curiosidad |
+| Cuerdas con sordina + coro suave | Distancia, memoria |
+| Trompas en 5ªs abiertas | Épica; cliché si se abusa |
+| Solo + silencio | Máxima atención |
+
+## Escritura coral / vocal
+
+- Rango cómodo, no extremo: la tesitura sostenida importa más que la nota más alta
+- Voice leading estricto: las voces internas se mueven lo mínimo
+- Texto inteligible pide notas más largas y registro medio
+- Vocales abiertas (a, o) para agudos y notas largas; cerradas (i, u) suenan tensas arriba
+
+## Producción-aware
+
+Si el material va a un mix con SFX y diálogo encima:
+
+- Dejar espacio en 500 Hz-2 kHz cuando puede haber VO
+- El sub (20-60 Hz) suele estar reservado a impactos — no llenarlo con música
+- Los transientes agudos compiten con feedback de UI: si el arreglo tiene mucho hi-hat/percusión brillante, el UI se pierde
+- Arreglos densos sobreviven mal a la compresión lossy de plataforma: el detalle en 6-20 kHz es lo primero que se va

package/skills/music-composition/references/rhythm-groove.md

@@ -0,0 +1,49 @@
+# Ritmo y Groove
+
+## Qué es el groove
+
+La relación entre una grilla implícita y dónde caen los eventos reales. Sin grilla no hay groove; sin desvío tampoco.
+
+Tres capas independientes:
+
+1. **Pulso** — el tempo y su subdivisión
+2. **Patrón** — qué subdivisiones se atacan
+3. **Feel** — cuánto se corren los ataques respecto de la grilla, y cómo se acentúan
+
+Un patrón correcto con feel plano suena a máquina. El mismo patrón con los backbeats 8-15 ms atrasados y acentuados suena a banda.
+
+## Recursos rítmicos
+
+| Recurso | Qué hace |
+|---|---|
+| **Síncopa** | Acentuar una subdivisión débil. El motor de casi todo groove popular |
+| **Anticipación** | Adelantar un ataque medio pulso antes del tiempo fuerte |
+| **Hemiola** | Agrupar 3 donde el metro dice 2 (o al revés). Tensión sin cambiar tempo |
+| **Desplazamiento** | Correr un patrón entero N subdivisiones. Mismo material, otro lugar |
+| **Aumentación / disminución** | Duplicar o partir las duraciones del patrón |
+| **Silencio en el downbeat** | El recurso más fuerte y el menos usado |
+| **Polirritmia** | Dos ciclos de distinta longitud simultáneos (3:2, 4:3). El compuesto se repite cada MCM |
+| **Cross-rhythm** | El acento contradice el metro sostenidamente |
+
+## Feel y microtiming
+
+- **Swing** — la primera corchea del par se alarga. Cuantificable como ratio (50:50 recto, ~60:40 swing suave, 66:33 swing fuerte, hasta tresillo)
+- **Laid back** — atacar unos ms después de la grilla. Sensación de relajación, peso
+- **Push** — atacar antes. Urgencia, ansiedad
+- **Flam** — dos instrumentos casi al unísono, corridos unos ms. Engorda el ataque
+
+Un desvío de 10-30 ms es feel. Arriba de ~50 ms se percibe como error o como otra subdivisión.
+
+## Métricas impares
+
+- **5/4, 7/8** — se sienten como agrupaciones asimétricas (5 = 3+2 o 2+3; 7 = 2+2+3, 3+2+2...). La agrupación importa más que el número
+- **Métrica mixta** — alternar compases. Funciona si el patrón de alternancia es reconocible
+- **Metro aditivo** — construir por células (2+2+3) en vez de dividir el compás
+
+Para juegos, las métricas impares complican la sincronización de música adaptativa: los sync points en compás/beat asumen un metro estable. Si el metro cambia, definir los puntos de transición en cues explícitos.
+
+## Groove en el arreglo
+
+- **Interlock** — cada instrumento ocupa subdivisiones que los otros dejan libres. El groove emerge del conjunto, no de una parte
+- **Densidad como dinámica** — más subdivisiones atacadas = más energía, sin subir volumen
+- **Espacio** — el groove vive en los silencios. Un patrón con todas las subdivisiones llenas no groovea, machaca

package/skills/procedural-audio/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: procedural-audio
+description: "Audio procedural: footsteps, viento, ambientes y superficies por sintesis en vez de samples. Decidir cuando conviene, disenar el modelo y presupuestar CPU. Usar para: sonido procedural, footsteps sinteticos, ambiente generativo, reducir memoria de audio."
+category: "audio"
+argument-hint: "[decide | footsteps | wind | ambience | budget]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit
+---
+# procedural-audio — Síntesis en vez de Samples
+
+Resuelve por generación los sistemas de audio donde samplear no escala: alta frecuencia de disparo cruzada con muchas dimensiones de variación.
+
+## Cuándo usar
+
+- El conteo de assets explota: superficies × intensidades × variantes
+- El presupuesto de memoria no da para la variación que el sistema necesita
+- La repetición se escucha aunque haya muchas variantes
+- El sonido tiene que responder de forma continua a un parámetro (velocidad, material, tamaño)
+
+## Cuándo NO usar
+
+Síntesis no es gratis: cuesta CPU por frame y trabajo de tuning. No la uses para sonidos hero (el arma principal, el tema de victoria) — ahí un sample bien diseñado gana en calidad y control. La síntesis rinde en lo frecuente y variable, no en lo memorable y único.
+
+---
+
+## Modos
+
+| Modo | Qué hace |
+|---|---|
+| `decide` | Solo la evaluación: ¿conviene sintetizar o samplear? Cuenta de assets y presupuesto |
+| `footsteps` | Diseña el modelo de pasos con resonancias por superficie |
+| `wind` | Diseña el modelo de viento por capas |
+| `ambience` | Diseña el ambiente híbrido: bed sampleado + detalle procedural |
+| `budget` | Solo el presupuesto de CPU y dónde corre cada modelo |
+
+## La decisión
+
+Evaluar dos ejes: **frecuencia de disparo** y **dimensiones de variación**.
+
+| | Pocas dimensiones | Muchas dimensiones |
+|---|---|---|
+| **Baja frecuencia** | Sample. Siempre | Sample con layer swapping |
+| **Alta frecuencia** | Sample + round-robin | **Procedural** |
+
+El caso canónico: footsteps sobre 6 superficies × 3 intensidades, con 20 variantes cada uno, son **360 archivos (~180 MB)** — y a pesar de eso la repetición se escucha en sesiones largas. Un modelo procedural son **~50 KB** y variación infinita.
+
+Antes de comprometerte, hacé la cuenta explícita:
+
+```
+assets = superficies × intensidades × variantes
+memoria ≈ assets × tamaño_promedio
+```
+
+Si el resultado es de tres dígitos en archivos, la síntesis ya se justifica sola.
+
+---
+
+## Presupuesto de CPU
+
+Esto es lo que decide si el modelo entra o no. Costos de referencia por fuente:
+
+| Operación | Costo |
+|---|---|
+| Footstep procedural | ~1-2 ms |
+| Síntesis de viento | ~0.5 ms/frame |
+| Convolución HRTF (512 taps) | ~2 ms/fuente |
+| Encode ambisónico | ~0.1 ms/fuente |
+| Decode ambisónico a binaural | ~1 ms total |
+
+**El presupuesto total de audio es 5-10% del frame time.** A 60 fps el frame son 16.6 ms, así que el audio entero dispone de ~0.8-1.7 ms. Un footstep procedural de 1-2 ms **no entra en un solo frame**: hay que amortizarlo (generar por adelantado, cachear el resultado, o generar en un thread de audio con buffer).
+
+Ese es el error de cálculo más común: leer "1-2 ms por footstep" y asumir que se puede hacer inline en el update. En un callback de audio de 5-10 ms a 48 kHz / 512 samples hay margen; en el frame de render no.
+
+---
+
+## Modelo de footsteps
+
+Tres componentes, cada uno con parámetros expuestos:
+
+1. **Impacto** — burst de ruido filtrado en la frecuencia de resonancia del material, envolvente muy corta
+2. **Resonancia del material** — filtro resonante en la frecuencia característica
+3. **Textura** — ruido con envolvente más larga: grava que se mueve, hojas, agua
+
+**Frecuencias de resonancia por superficie:**
+
+| Superficie | Frecuencia | Textura |
+|---|---|---|
+| Concreto | 150 Hz | Mínima, ataque seco |
+| Madera | 250 Hz | Resonancia larga, crujido |
+| Metal | 500 Hz | Cola muy larga, armónicos |
+| Grava | 300 Hz | Ruido dominante, larga |
+
+**Parámetros de entrada** desde gameplay, todos normalizados 0-1:
+
+| Parámetro | Efecto |
+|---|---|
+| Material | Selecciona frecuencia y perfil de textura |
+| Intensidad (velocidad) | Amplitud, brillo, duración del ataque |
+| Peso del personaje | Frecuencia base, cantidad de sub |
+| Humedad de superficie | Capa de agua, amortiguación de la resonancia |
+
+La variación sale de randomizar levemente cada parámetro por paso, no de elegir entre archivos. Eso es lo que hace la variación infinita.
+
+## Modelo de viento
+
+Ruido filtrado con modulación lenta, en capas:
+
+- **Base** — ruido rosa con low-pass, cutoff modulado lento (0.05-0.2 Hz)
+- **Ráfagas** — amplitud modulada por ruido de baja frecuencia, con picos ocasionales
+- **Silbido** — filtro resonante en 800 Hz-2 kHz, solo cuando la intensidad supera un umbral
+- **Detalle** — high-pass sutil que aparece con la intensidad
+
+Parámetro principal: intensidad 0-1, mapeada a cutoff, profundidad de modulación y presencia de silbido. Un solo parámetro maneja de brisa a tormenta.
+
+## Ambientes
+
+La síntesis pura de ambiente suele sonar sintética. El enfoque híbrido gana:
+
+- **Bed** — sample loopeado largo (el único sample del sistema)
+- **Detalle** — one-shots posicionados por lógica procedural: qué sonido, cada cuánto, desde dónde
+- **Modulación** — filtro y volumen del bed manejados por parámetros de entorno (interior/exterior, clima, hora)
+
+La sensación de "vivo" viene de la **distribución temporal y espacial** de los detalles, no de sintetizarlos. Un pájaro sampleado que aparece en posiciones y momentos impredecibles suena más vivo que uno sintetizado en loop fijo.
+
+---
+
+## Proceso
+
+1. **Hacer la cuenta** de assets y memoria; si no justifica, parar y usar samples
+2. **Presupuestar CPU** contra el 5-10% del frame, y decidir dónde corre (frame vs thread de audio vs precomputado)
+3. **Diseñar el modelo** por componentes con parámetros expuestos
+4. **Mapear los parámetros** de gameplay, normalizados y clampeados en el boundary
+5. **Definir el fallback** — qué suena si el modelo se desactiva por presupuesto en plataforma baja
+6. **Escribir** — preguntar "¿Escribo el diseño a `<path>`?" antes de usar Write
+
+### Fallback obligatorio
+
+Toda plataforma tiene un piso. Si el modelo procedural no entra en la plataforma más baja del target, hace falta un camino de samples reducido. Decidirlo en el diseño, no cuando falla la certificación.
+
+---
+
+## Verdict
+
+- **READY** — la cuenta justifica la síntesis, el presupuesto de CPU cierra con dónde corre, los parámetros están mapeados y hay fallback
+- **CONCERNS** — el modelo está diseñado pero el presupuesto de CPU no se verificó en la plataforma más baja, o falta el fallback
+- **BLOCKED** — no está claro el conteo de assets ni la frecuencia de disparo, así que no se puede decidir si conviene
+
+## Anti-patterns
+
+> → Read references/anti-patterns.md
+
+## Next steps
+
+- `/sfx-design` para los sonidos hero, que siguen siendo samples
+- `/audio-audit` para medir el costo real de CPU en runtime, no el estimado
+- `/middleware-integration` para exponer los parámetros como RTPCs
+- `/spatial-audio` si las fuentes procedurales además se posicionan en 3D

package/skills/procedural-audio/references/anti-patterns.md

@@ -0,0 +1,45 @@
+# Audio Procedural — Anti-patterns
+
+## Síntesis por elegancia
+
+Procedural no es mejor por ser procedural. Para un sonido hero, un sample bien diseñado gana en calidad, en control y en tiempo de producción. La síntesis rinde donde samplear no escala; en el resto es trabajo extra con peor resultado.
+
+## Confundir el presupuesto de frame con el de callback
+
+"1-2 ms por footstep" leído como "se puede hacer inline en el update" es el error de cálculo más frecuente. El audio entero dispone de 0.8-1.7 ms por frame a 60 fps. El footstep hay que amortizarlo: precomputar, cachear, o generarlo en el thread de audio con buffer.
+
+## No medir, estimar
+
+Los costos de referencia son puntos de partida, no promesas. El costo real depende de plataforma, compilador y qué más corre. Medir con el profiler del middleware antes de comprometer la arquitectura.
+
+## Un solo parámetro sin curva
+
+Mapear intensidad 0-1 linealmente a amplitud produce una respuesta que se siente muerta en la mitad del rango. La percepción de volumen y de brillo es logarítmica: la curva importa tanto como el rango.
+
+## Parámetros sin clamp
+
+Un valor de velocidad que llega en 3.7 cuando el modelo espera 0-1 produce ruido blanco a todo volumen. Normalizar y clampear en el boundary, del lado de gameplay.
+
+## Sintetizar el ambiente entero
+
+El ambiente puramente sintético suena sintético. La sensación de "vivo" viene de la distribución temporal y espacial de los detalles, no de generarlos. Bed sampleado + detalles posicionados proceduralmente gana.
+
+## Variación sin límites perceptuales
+
+Randomizar los parámetros con rango amplio produce pasos que suenan a materiales distintos entre sí. La variación tiene que ser suficiente para no repetir y chica para no romper la identidad.
+
+## Sin fallback de plataforma
+
+El modelo entra cómodo en PC y no entra en el target más bajo. Si eso se descubre en certificación, hay que rehacer el sistema contra reloj. El camino de samples reducido se decide en el diseño.
+
+## Reemplazar todo de golpe
+
+Migrar el sistema de audio entero a procedural en un paso hace imposible saber qué regresión vino de dónde. Un sistema por vez, midiendo antes y después.
+
+## Ignorar que sigue siendo una fuente 3D
+
+Un footstep procedural igual necesita posición, atenuación y — si son varios personajes — límite de voces. La síntesis resuelve la memoria, no la gestión de voces.
+
+## Modelo sin parámetros expuestos
+
+Si el modelo está hardcodeado, no es procedural: es un sample generado en runtime, con todos los costos y ninguna ventaja. El valor está en que gameplay pueda modularlo.

package/skills/sfx-design/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: sfx-design
+description: "Diseno de efectos de sonido: capas attack/body/tail, variacion y round-robin, pitch randomization, layering de impactos, anti-repeticion. Usar para: disenar SFX, sonidos de impacto, armas, feedback de accion."
+category: "audio"
+argument-hint: "[sound-name | layers | variation | review]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit
+---
+# sfx-design — Diseño de Efectos
+
+Diseña *cómo suena* un efecto: de qué capas se construye, cómo varía, y por qué se lee como el evento que representa.
+
+`/audio-spec` escribe el contrato (qué lo dispara, con qué límites). Esta skill diseña el sonido.
+
+## Cuándo usar
+
+- Sonidos hero que merecen diseño individual: el arma principal, el golpe crítico, el skill definitivo
+- Cuando un efecto "no se siente" y hay que diagnosticar por qué
+- Cuando la biblioteca se escucha repetitiva y hay que resolver variación
+- Antes de grabar o comprar assets, para saber qué buscar
+
+## Modos
+
+| Modo | Qué hace |
+|---|---|
+| `sound-name` | Diseña un efecto concreto de punta a punta |
+| `layers` | Solo la anatomía por capas: qué banda ocupa cada una |
+| `variation` | Solo el plan de variación: variantes, round-robin, randomización, layer swapping |
+| `review` | Diagnostica un efecto existente contra la tabla de síntomas |
+
+## Input
+
+1. Leer audio bible (paleta, frequency allocation) y el spec del sonido si existe
+2. Preguntar al usuario: qué evento representa, qué debe sentir el jugador, y si hay referencia sonora
+3. Identificar la restricción: ¿este sonido suena una vez por partida o cien veces por minuto? Eso cambia todo
+
+---
+
+## Anatomía de un efecto
+
+Todo efecto se lee en tres partes. Diseñarlas por separado es la diferencia entre un sonido que funciona y uno que "le falta algo":
+
+| Capa | Duración típica | Qué comunica | Se percibe como |
+|---|---|---|---|
+| **Attack** | 1-20 ms | Qué material, cuánta fuerza | Impacto, precisión, "punch" |
+| **Body** | 20-200 ms | Qué tamaño, qué objeto | Peso, escala |
+| **Tail** | 50 ms-2 s | Dónde está, qué espacio | Ambiente, distancia, potencia |
+
+**Diagnóstico por síntoma:**
+
+| Síntoma | Capa culpable | Arreglo |
+|---|---|---|
+| "Se siente débil" | Attack sin transiente | Sumar una capa de click/crack corta y brillante |
+| "No tiene peso" | Body sin graves | Sumar sub o cuerpo en 60-150 Hz |
+| "Suena a sample de librería" | Tail genérico o ausente | Cola propia, o reverb del espacio real del juego |
+| "Es confuso, no se lee" | Demasiadas capas peleando | Sacar capas hasta que se lea; casi siempre 3 alcanzan |
+| "Se siente lento" | Attack largo | Recortar el pre-ataque; el transiente tiene que estar en los primeros ms |
+| "Molesta después de un rato" | Energía en 2-6 kHz | Bajar; esa banda fatiga rápido |
+
+## Layering
+
+Construir por función, no por acumulación. Un impacto potente típico:
+
+1. **Sub** (40-80 Hz) — peso físico. Corto, 60-120 ms. En un handheld no se va a oír: no puede ser la única fuente de fuerza
+2. **Punch** (100-300 Hz) — el cuerpo que se percibe en cualquier speaker
+3. **Crack** (2-5 kHz) — la definición y el material
+4. **Tail** — el espacio
+
+**Regla:** cada capa ocupa una banda distinta. Si dos capas pelean la misma banda, una sobra. Es el mismo principio de frequency allocation del audio bible, aplicado dentro de un solo sonido.
+
+Cuatro capas es el techo práctico. Arriba de eso el sonido pierde legibilidad y ganás solo peso de archivo.
+
+## Variación y anti-repetición
+
+Un sonido sin variación se vuelve audible **como sonido** en vez de como evento. En eventos frecuentes eso pasa alrededor de los 20 minutos de juego.
+
+Las herramientas, de más a menos efectiva:
+
+| Técnica | Cómo | Nota |
+|---|---|---|
+| **Variantes reales** | 4-8 grabaciones/renders distintos | La única que varía el timbre de verdad |
+| **Round-robin** | Recorrer variantes en orden, sin repetir la última | Le gana a random puro: random repite |
+| **Pitch randomization** | ±2% a ±4% | ±3% es variación; ±20% cambia el objeto |
+| **Volume randomization** | ±1 a ±2 dB | Sutil, siempre suma |
+| **Layer swapping** | Fijar el body, rotar attack y tail | Combinatorio: 3 attacks × 3 tails = 9 sonidos con 6 assets |
+| **Filtro aleatorio** | Cutoff ±10% | Último recurso, se nota poco |
+
+**Layer swapping es la de mejor relación resultado/costo** y la menos usada. Con 4 attacks, 2 bodies y 3 tails tenés 24 combinaciones desde 9 archivos.
+
+Si el evento es de altísima frecuencia y muchas dimensiones (footsteps sobre 6 superficies × 3 intensidades), la respuesta no es más variantes: es `/procedural-audio`.
+
+## Estilización vs realismo
+
+El sonido realista casi nunca es el sonido correcto. Un disparo real es un chasquido corto y poco impresionante; una puerta real suena a nada.
+
+Criterio: el efecto tiene que comunicar **la función en el gameplay**, no la física. Si el arma hace 40 de daño y la otra 90, tienen que sonar distintas en peso aunque sean el mismo calibre. La legibilidad le gana al realismo siempre que compiten.
+
+---
+
+## Proceso
+
+1. **Definir la lectura** — en una frase, qué tiene que entender el jugador al escucharlo
+2. **Diseñar las capas** por función, con banda asignada a cada una
+3. **Definir la variación** — cuántas variantes, qué randomización, round-robin o no
+4. **Chequear contra el bible** — ¿respeta la paleta y la allocation de frecuencias?
+5. **Chequear en contexto** — un sonido nunca se juzga solo: con música, ambiente y otros 10 SFX encima
+6. **Escribir** — preguntar "¿Escribo el diseño a `<path>`?" antes de usar Write
+
+### Chequeo en contexto
+
+El error más caro del sound design es aprobar sonidos en aislamiento. Un efecto perfecto solo puede desaparecer en la mezcla o taparle el ataque a otro. Evaluar siempre con el resto sonando, y al volumen real de juego.
+
+---
+
+## Verdict
+
+- **READY** — el sonido tiene lectura definida, capas por banda, plan de variación, y se validó en contexto
+- **CONCERNS** — está diseñado pero no se probó con el resto del mix, o la variación no alcanza para su frecuencia de uso
+- **BLOCKED** — no está claro qué evento representa o falta la dirección del audio bible
+
+## Anti-patterns
+
+> → Read references/anti-patterns.md
+
+## Next steps
+
+- `/audio-spec` para formalizar el contrato del evento (concurrencia, cooldown, prioridad)
+- `/procedural-audio` si el conteo de variantes se vuelve inmanejable
+- `/audio-mix` para ubicarlo en la jerarquía de buses
+- `/middleware-integration` para implementar el round-robin y la randomización en containers

package/skills/sfx-design/references/anti-patterns.md

@@ -0,0 +1,53 @@
+# SFX Design — Anti-patterns
+
+## Aprobar en aislamiento
+
+El error más caro. Un sonido perfecto en solo desaparece bajo música y ambiente, o le tapa el ataque a otro. Todo efecto se juzga en contexto y al volumen real de juego.
+
+## Apilar capas hasta que "suene grande"
+
+Ocho capas no suenan más grandes que tres: suenan barrosas. La grandeza sale de la separación de bandas y del contraste con el silencio previo, no de la cantidad. Cuatro capas es el techo práctico.
+
+## Dos capas en la misma banda
+
+Si el sub y el punch pelean en 80 Hz, una de las dos está de más. Cada capa, su banda.
+
+## Depender del sub para la fuerza
+
+En el speaker de un handheld o en earbuds baratos no hay 40 Hz. Si toda la potencia del impacto vive ahí, en la mitad de los dispositivos el sonido es un chasquido. La fuerza tiene que leerse también en 100-300 Hz.
+
+## Pitch randomization exagerada
+
+±20% no es variación, es otro objeto. El arma parece cambiar de calibre entre disparos. ±2-4% y round-robin.
+
+## Random puro en vez de round-robin
+
+Random repite: con 4 variantes, la probabilidad de escuchar la misma dos veces seguidas es 25%. Y la repetición inmediata es exactamente lo que se quería evitar. Round-robin excluyendo la última.
+
+## Una sola variante en eventos frecuentes
+
+Se vuelve audible como sonido a los 20 minutos. Si el evento se dispara seguido, mínimo 4 variantes o layer swapping.
+
+## Perseguir realismo
+
+Un disparo real es poco impresionante y una puerta real suena a nada. El efecto comunica función de gameplay, no física. Si dos armas hacen daño distinto, tienen que sonar distinto en peso.
+
+## Attack con pre-roll
+
+50 ms de silencio o de aire antes del transiente hacen que la acción se sienta laggeada aunque el código sea instantáneo. El transiente va en los primeros milisegundos del archivo.
+
+## Energía gratis en 2-6 kHz
+
+Es la banda donde el oído es más sensible y la que fatiga más rápido. Sirve para definición y para feedback de UI; usada de más en todos los SFX, el juego se vuelve cansador en sesiones largas.
+
+## Reverb bakeado en el asset
+
+Si la cola trae el espacio grabado, el sonido no se puede reubicar: suena a catedral dentro de un armario. La cola propia va seca y el espacio lo pone el middleware por zona.
+
+## Tail que ignora el 3D
+
+Una cola larga en un sonido 3D sigue sonando cuando la fuente ya se alejó, o se corta abrupto al salir del rango. Definir la atenuación considerando la cola, no solo el ataque.
+
+## Escalar por número de variantes
+
+20 samples × 6 superficies × 3 intensidades = 360 archivos y ~180 MB, y aun así se escucha repetición. Cuando el problema tiene varias dimensiones, la respuesta es síntesis, no más grabaciones.