claude-code-arcane 2.0.0 → 2.2.0

package/skills/second-brain/references/templates/vault-CLAUDE.md

@@ -0,0 +1,127 @@
+# <NOMBRE DEL VAULT>
+
+Vault de Obsidian usado como segundo cerebro. Este archivo es el contrato: Claude Code lo lee al inicio de cada sesión y de acá saca dónde va cada cosa. Si una convención cambia, se cambia acá primero.
+
+## Quién soy
+
+<Rol, en qué proyectos estoy, qué temas me interesan. Dos o tres líneas: sirve para que las síntesis tengan contexto y no sean genéricas.>
+
+## Rutas
+
+Contrato de rutas: los skills escriben en **roles**, y esta tabla dice qué carpeta es cada rol en este vault. Si cambiás una carpeta de lugar, se cambia acá y todo lo demás sigue funcionando.
+
+| Rol | Ruta en este vault |
+|---|---|
+| `inbox` | `_inbox` |
+| `daily` | `Reflect/Daily` |
+| `weekly` | `Reflect/Weekly` |
+| `monthly` | `Reflect/Monthly` |
+| `atomic` | `03_Resources` |
+| `hubs` | `Hubs` |
+| `projects` | `01_Projects` |
+| `areas` | `02_Areas` |
+| `archive` | `04_Archive` |
+| `templates` | `Templates` |
+
+Y tres archivos fijos en la raíz: este `CLAUDE.md` (el contrato), `hot.md` (el caché de contexto reciente, lo reescribe `/review-dump`) y `codebases.md` (el puente a los repos, si hay código).
+
+Un rol que este vault no usa se marca `(no usa)` en vez de borrar la fila: así queda explícito que la ausencia fue una decisión.
+
+Los scripts reciben esto por flag: `--role hubs=Hubs --role atomic=03_Resources`.
+
+## Estructura
+
+| Carpeta | Qué vive acá |
+|---|---|
+| `_inbox/` | Captura cruda, un archivo por día (`YYYY-MM-DD dump.md`). Sin estructura, sin tags, sin pensar. El sufijo evita que el nombre choque con el del daily. |
+| `Reflect/Daily/` | Síntesis del día (`YYYY-MM-DD.md`), la crea `/review-dump`. |
+| `Reflect/Weekly/` | Retrospectiva semanal (`YYYY-Www.md`). |
+| `Reflect/Monthly/` | Balance del mes (`YYYY-MM.md`). |
+| `01_Projects/` | Algo con deadline o resultado definido. Cuando cierra, va a `04_Archive/`. |
+| `02_Areas/` | Responsabilidad continua sin fecha de fin (salud, finanzas, un rol). |
+| `03_Resources/` | Notas atómicas: una idea por nota, plano, sin subcarpetas. |
+| `04_Archive/` | Cerrado. Nunca se borra nada, se archiva. |
+| `Hubs/` | Una nota por entidad que importa: persona, herramienta, concepto, empresa. |
+| `Bases/` | Vistas `.base`. |
+| `Templates/` | Mis plantillas. Claude no las edita. |
+
+## Contrato de frontmatter
+
+Todo campo que se escriba tiene que estar acá. Un campo que no está declarado no se inventa: se propone y se agrega primero.
+
+```yaml
+---
+created: YYYY-MM-DD        # ISO, nunca se reescribe
+type: daily                # daily | weekly | monthly | dump | atomic | hub | project | area | clip
+status: seed               # madurez, solo en atomic, hub y clip (ver abajo)
+tags: []
+---
+```
+
+### `status`: madurez de la nota
+
+Solo para `atomic`, `hub` y `clip`. Las notas periódicas (`daily`, `weekly`, `monthly`, `dump`) no lo llevan: son registro, no conocimiento, y no maduran.
+
+| Valor | Significa | Efecto |
+|---|---|---|
+| `seed` | Apenas plantada, incompleta a propósito | No cuenta como hueca. Si sigue `seed` a los 30 días, el audit la marca: una semilla que no crecio es la falla clasica del vault. |
+| `provisional` | Tiene cuerpo pero no la sostendría en una discusión | Default de una nota recién escrita con contenido |
+| `evergreen` | Dice lo que tiene que decir. Puede quedarse quieta años | **No cuenta como stale.** Es lo que distingue una nota que ya hizo su trabajo de una abandonada. |
+| `contested` | Contradice a otra nota del vault y no está resuelto | El audit la lista para que un review la mire. La contradicción se preserva, no se resuelve sola. |
+| `archived` | Cerrada | Fuera del alcance del audit, viva donde viva |
+
+Sin este campo el audit no puede distinguir una nota de referencia que terminó su trabajo de un stub que nunca creció, y reporta las dos como stale.
+
+**Los proyectos usan el mismo campo con otro vocabulario** (`activo | pausado | cerrado`): es su ciclo de vida, no su madurez. El audit solo interpreta los cinco valores de arriba, así que un `activo` le resulta inerte y el proyecto se evalúa como cualquier otra nota. Si eso te molesta, renombralo acá y el contrato manda.
+
+Campos adicionales por tipo:
+
+| `type` | Campos propios |
+|---|---|
+| `project` | `status: activo \| pausado \| cerrado`, `deadline` (opcional), `repos:` si tiene código |
+| `clip` | `source` (URL), `author` (opcional) |
+| `hub` | `aliases` (nombres alternativos de la entidad), `repos:` si la entidad tiene código |
+
+`repos:` es el puente al código: la lista de repos que implementan esa entidad. Se traduce a path local en `codebases.md`. **El vault apunta, no copia:** la arquitectura vive en el repo.
+
+## Reglas de link
+
+- **Los links van hacia arriba, nunca hacia abajo.** Dump linkea a hubs y proyectos. Daily linkea al dump. Weekly linkea a los dailies. Monthly linkea a los weeklies. Los backlinks de Obsidian dan la dirección inversa gratis.
+- **Ninguna nota se cierra sin al menos un `[[wikilink]]`.** Si no hay a qué linkearla, falta un hub file.
+- `[[wikilinks]]` para lo interno, `[texto](url)` solo para URLs externas.
+
+## Tareas
+
+Las tareas viven en la nota a la que pertenecen, no en una lista central. Una tarea de un proyecto vive en la nota del proyecto; una que apareció en el día vive en el dump de ese día.
+
+**Una tarea abierta no se arrastra al día siguiente.** Queda en su día marcada como cancelada (`- [-]`) y se crea de nuevo donde corresponda. No haber hecho algo un día es información.
+
+## Qué puede hacer Claude
+
+- Crear y editar notas, clasificar el dump, actualizar hub files, generar dailies/weeklies/monthlies, buscar en el vault, proponer links.
+
+## Qué no puede hacer Claude
+
+- Borrar notas (mueve a `04_Archive/`).
+- Renombrar o mover notas sin que yo lo apruebe.
+- Editar `Templates/` ni nada dentro de `.obsidian/`.
+- Escribir la sección de reflexión de los reviews: los hechos los sintetiza Claude, la interpretación la escribo yo.
+- Editar en masa: los cambios que afectan muchas notas van por `/vault-tidy` con approval.
+
+## Plugins instalados
+
+<Completado por `/second-brain setup` con la detección real. Lo que no está en esta lista no se usa en las notas.>
+
+## Quién escribe qué
+
+- **Autorado** (lo escribo yo, Claude no lo toca sin approval): dumps, notas atómicas, hubs, clips, proyectos, este archivo, y la `## Reflexión` de los reviews.
+- **Sintetizado** (Claude lo escribe con mi OK y queda como nota): dailies, weeklies, monthlies, el `## Historial` de los hubs.
+- **Proyectado** (Claude lo reescribe sin preguntar, es derivado y descartable): `hot.md`, `.vault-index.json`, las vistas `.base`. No los edito a mano porque se pisan.
+
+## Uso desde otros proyectos
+
+Otros repos pueden leer este vault. El orden de lectura es `hot.md` → búsqueda con `vault_index.py` → el hub del tema → la nota. **No se lee el vault para preguntas generales de programación**, y no se escribe en él desde otro proyecto salvo pedido explícito. Receta completa: `/second-brain link`.
+
+## Git
+
+Este vault es un repo git. Antes de una corrida que escribe varias notas, el árbol tiene que estar limpio: es el único undo confiable.

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.

package/skills/spatial-audio/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: spatial-audio
+description: "Audio espacial: HRTF/binaural, Ambisonics, panning, curvas de atenuacion, oclusion y obstruccion, reverb por zona, y presupuesto de CPU por tecnica. Usar para: sonido 3D, audio posicional, VR audio, oclusion, decidir HRTF vs panning."
+category: "audio"
+argument-hint: "[decide | hrtf | ambisonics | occlusion | budget]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit
+---
+# spatial-audio — Audio Posicional
+
+Decide qué técnica de espacialización usar por fuente, y presupuesta el costo. La decisión correcta casi nunca es "la mejor técnica para todo".
+
+## Cuándo usar
+
+- Definir la estrategia de espacialización de un juego o experiencia VR
+- El audio 3D come demasiado CPU
+- Las fuentes no se localizan bien, o suenan "adentro de la cabeza"
+- Implementar oclusión y obstrucción
+- Diseñar reverb por zona
+
+## Input
+
+1. Leer audio bible y el presupuesto de performance del proyecto
+2. Determinar: ¿hay auriculares garantizados (VR) o hay que funcionar en speakers?
+3. Contar las fuentes simultáneas esperadas por categoría
+4. Preguntar al usuario: plataforma target más baja y fps objetivo
+
+---
+
+## Presupuesto — el número que decide todo
+
+| Técnica | Costo |
+|---|---|
+| Convolución HRTF (512 taps) | **~2 ms por fuente** |
+| Encode ambisónico | ~0.1 ms por fuente |
+| Decode ambisónico a binaural | ~1 ms total (una vez, no por fuente) |
+| Panning estéreo / vector-based | despreciable |
+| Atenuación por distancia + filtro | despreciable |
+
+**El audio entero dispone del 5-10% del frame time.** A 60 fps son 16.6 ms de frame, así que el audio tiene ~0.8-1.7 ms.
+
+Ese número mata la idea de HRTF universal de entrada: **50 fuentes × 2 ms = 100 ms de CPU**, seis veces el frame completo. No es "costoso": es imposible.
+
+Presupuesto realista: **3-5 fuentes con HRTF**, el resto por otras técnicas.
+
+---
+
+## Decisión por fuente
+
+| Situación | Técnica | Por qué |
+|---|---|---|
+| 3-5 fuentes críticas, con auriculares | **HRTF** | Localización precisa, incluida elevación |
+| Ambiente, campo difuso | **Ambisonics** | Costo por fuente casi nulo; un solo decode |
+| Fuentes lejanas o poco importantes | **Panning + atenuación** | Gratis, e igual son indistinguibles |
+| Música, UI | **2D, sin espacializar** | No tienen posición en el mundo |
+| Diálogo del jugador / narrador | **2D o pseudo-3D** | Tiene que ser siempre inteligible |
+| Fuentes en speakers (no auriculares) | **Panning / surround** | HRTF en speakers no funciona: asume oídos, no una sala |
+
+**HRTF asume auriculares.** En speakers el crosstalk entre canales destruye las claves binaurales y el resultado es peor que un panning honesto. Si la plataforma no garantiza auriculares, HRTF necesita detección de ruta o queda descartado.
+
+**Estrategia recomendada:** un presupuesto explícito de "slots HRTF" asignado por prioridad dinámica — la fuente más importante y más cercana se lleva el slot, y al alejarse lo devuelve. Todo lo demás, Ambisonics y panning.
+
+---
+
+## Curvas de atenuación
+
+La atenuación es lo que más aporta a la percepción de distancia, y es gratis. Componentes:
+
+| Componente | Qué comunica |
+|---|---|
+| **Volumen por distancia** | Distancia base |
+| **Filtro low-pass creciente** | El aire absorbe agudos: lejano = más opaco |
+| **Reducción de spread** | Cerca es ancho, lejos es puntual |
+| **Aumento de reverb (wet/dry)** | Lejano = más proporción de espacio |
+
+**Los cuatro juntos** venden la distancia mucho mejor que el volumen solo. Un sonido que solo baja de volumen se percibe como "más silencioso", no como "más lejos".
+
+Definir siempre `min distance` (dentro de la cual no atenúa) y `max distance` (fuera de la cual no suena), y la forma de la curva. Log es lo más natural para la mayoría de las fuentes; lineal sirve cuando querés control preciso del rango audible.
+
+## Oclusión y obstrucción
+
+Dos fenómenos distintos que se confunden seguido:
+
+| | Qué es | Efecto |
+|---|---|---|
+| **Obstrucción** | Algo bloquea el camino directo, pero el sonido reflejado llega | Baja el directo, mantiene el reverb. Se oye "alrededor" |
+| **Oclusión** | Directo y reflejado bloqueados: pared sólida | Baja los dos + low-pass fuerte |
+
+Confundirlas produce el bug clásico: un enemigo detrás de una columna se vuelve inaudible (se aplicó oclusión donde correspondía obstrucción).
+
+**Costo:** la parte cara no es el filtro, es el raycast. Con muchas fuentes hay que:
+- Limitar los raycasts por frame y repartirlos entre frames
+- Cachear el resultado y actualizar con menos frecuencia que el frame
+- Interpolar el valor de oclusión hacia el target, nunca aplicarlo de golpe (el salto se escucha)
+
+## Reverb por zona
+
+- Definir zonas con un preset de reverb cada una, y **crossfade en las transiciones** — un cambio instantáneo de reverb es muy audible
+- El envío a reverb depende de la distancia (ver curvas arriba)
+- Las fuentes 2D (música, UI) normalmente **no** van a reverb de zona
+- La cola del reverb tiene que seguir sonando al cambiar de zona, o se corta de forma antinatural
+
+## VR y consideraciones específicas
+
+- **Head tracking obligatorio:** la posición de las fuentes se actualiza con la cabeza. Latencia alta rompe la ilusión y marea
+- **Elevación importa:** es lo que HRTF aporta y el panning no puede
+- **Auriculares garantizados:** es el único contexto donde HRTF es la elección obvia
+- **Presupuesto más ajustado:** 90 fps deja ~11 ms de frame, así que el audio tiene menos margen aún
+
+---
+
+## Proceso
+
+1. **Contar fuentes** simultáneas por categoría
+2. **Presupuestar** contra el 5-10% del frame en la plataforma más baja
+3. **Asignar técnica por categoría**, con slots HRTF explícitos y prioridad dinámica
+4. **Definir curvas** de atenuación con los cuatro componentes
+5. **Definir oclusión vs obstrucción** por tipo de geometría, con presupuesto de raycasts e interpolación
+6. **Definir zonas** de reverb y sus transiciones
+7. **Escribir** — preguntar "¿Escribo la estrategia a `<path>`?" antes de usar Write
+
+---
+
+## Verdict
+
+- **READY** — cada categoría tiene técnica asignada, el presupuesto cierra en la plataforma más baja, y oclusión/obstrucción están diferenciadas
+- **CONCERNS** — la estrategia existe pero el presupuesto no se midió, o HRTF se asume sin verificar que haya auriculares
+- **BLOCKED** — falta el conteo de fuentes simultáneas o el presupuesto de performance del proyecto
+
+## Anti-patterns
+
+> → Read references/anti-patterns.md
+
+## Next steps
+
+- `/audio-audit` para medir CPU y voice count reales en runtime
+- `/middleware-integration` para implementar atenuaciones, oclusión y buses de reverb
+- `/procedural-audio` si las fuentes ambiente son muchas y conviene generarlas
+- `/audio-mix` para el reparto de buses y el ducking del diálogo

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

@@ -0,0 +1,53 @@
+# Audio Espacial — Anti-patterns
+
+## HRTF en todas las fuentes
+
+50 fuentes × 2 ms = 100 ms de CPU, contra un frame de 16.6 ms a 60 fps. No es costoso: es seis veces imposible. El presupuesto real es 3-5 fuentes con HRTF y el resto por Ambisonics o panning.
+
+## HRTF en speakers
+
+HRTF asume auriculares. En speakers el crosstalk entre canales destruye las claves binaurales y suena peor que un panning honesto. Si no hay auriculares garantizados, hace falta detección de ruta o se descarta.
+
+## Volumen como única clave de distancia
+
+Un sonido que solo baja de volumen se percibe como "más silencioso", no como "más lejos". Hacen falta los cuatro componentes: volumen, low-pass creciente, spread decreciente y más reverb.
+
+## Confundir oclusión con obstrucción
+
+Aplicar oclusión total donde había obstrucción hace que un enemigo detrás de una columna sea inaudible. Obstrucción baja el directo y mantiene el reflejado; oclusión baja los dos.
+
+## Raycasts sin presupuesto
+
+La parte cara de la oclusión es el raycast, no el filtro. Con 30 fuentes haciendo raycast por frame el costo se dispara. Limitar, repartir entre frames, cachear.
+
+## Oclusión sin interpolar
+
+Aplicar el valor de golpe produce un salto muy audible cada vez que el jugador cruza el borde de una geometría. Interpolar siempre hacia el target.
+
+## Curvas sin min/max distance
+
+Dejar el default del middleware produce sonidos audibles a 200 m o que desaparecen a 3 m. Los dos valores y la forma de la curva son parte del spec.
+
+## Reverb de zona con cambio instantáneo
+
+El salto de preset se escucha como un corte. Crossfade en la transición, y dejar que la cola anterior termine.
+
+## Música y UI espacializadas
+
+No tienen posición en el mundo. Espacializarlas produce paneos raros y costo inútil.
+
+## Diálogo tratado como una fuente 3D más
+
+Si el diálogo importante se ocluye y se atenúa como cualquier SFX, el jugador pierde información. Suele necesitar un tratamiento pseudo-3D: dirección sí, oclusión no.
+
+## Presupuestar contra la plataforma más alta
+
+El modelo entra en PC y no en el target más bajo. El presupuesto se hace contra el piso, no contra el techo.
+
+## Ambisonics para fuentes puntuales importantes
+
+Ambisonics brilla en campo difuso y ambiente. Para la fuente crítica que el jugador tiene que localizar con precisión, no reemplaza a HRTF.
+
+## Ignorar el presupuesto más ajustado de VR
+
+90 fps deja ~11 ms de frame. Un plan de espacialización calculado para 60 fps no entra.

package/skills/ui-sound-design/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: ui-sound-design
+description: "Sonido de interfaz y feedback: duraciones y niveles por tipo de evento, jerarquia de feedback, coordinacion con haptics, respeto del volumen del sistema, accesibilidad. Usar para: sonidos de UI, feedback de menu, notificaciones, sonido de app."
+category: "audio"
+argument-hint: "[set | event-name | review | haptics]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit
+---
+# ui-sound-design — Feedback de Interfaz
+
+Diseña el sonido que confirma acciones. Es el audio que el usuario escucha más veces y el que más rápido se vuelve molesto si está mal calibrado.
+
+## Cuándo usar
+
+- Definir el set de sonidos de UI de un juego o una app
+- El feedback se siente molesto, invasivo o inconsistente
+- Falta jerarquía: todo suena igual de importante
+- Coordinar audio con haptics
+
+## Input
+
+1. Leer audio bible (paleta, frequency allocation, mix hierarchy)
+2. Listar los eventos de UI reales de la interfaz
+3. Preguntar al usuario: plataforma (desktop / consola / móvil), si hay haptics, y si el juego se juega en sesiones largas
+
+---
+
+## Especificaciones por tipo
+
+Estos rangos son el punto de partida calibrado. Salirse de ellos requiere razón.
+
+| Tipo | Duración | Carácter | Nivel |
+|---|---|---|---|
+| **Tap / hover** | 30-80 ms | Click suave, alta frecuencia | −24 dB |
+| **Confirmación** | 80-150 ms | Transiente definido, neutro | −21 dB |
+| **Éxito** | 150-300 ms | Tono ascendente, positivo | −18 dB |
+| **Error** | 200-400 ms | Descendente, menor | −18 dB |
+| **Notificación** | 300-800 ms | Distintivo, llama atención | −18 dB |
+| **Transición / navegación** | 100-250 ms | Movimiento sutil | −24 dB |
+| **Toggle** | 40-100 ms | Dos estados distinguibles | −24 dB |
+
+**El nivel es lo que más se equivoca.** Los sonidos de UI van entre **−18 y −24 dB** relativos al material de gameplay. Un click a −3 dB compite con la acción del juego y agota en minutos.
+
+Regla de proporcionalidad: **el nivel y la duración son proporcionales a la importancia del evento**. Un hover es lo más corto y lo más bajo. Un error de transacción es lo más largo y lo más alto. Si el hover y el error suenan parecido, no hay jerarquía.
+
+## Frecuencia y fatiga
+
+El feedback de UI vive en **2-6 kHz**: es donde el oído es más sensible, así que un sonido bajo se lee claro sin volumen. Es también la banda que **más rápido fatiga**.
+
+Consecuencias de diseño:
+
+- Transientes cortos, no tonos sostenidos: la energía breve informa sin cansar
+- En un juego de sesiones largas, correr el feedback hacia abajo (1-3 kHz) reduce la fatiga a costa de algo de claridad
+- Si el juego tiene mucha percusión brillante o hi-hats, el UI compite: bajar el UI no alcanza, hay que hacerle lugar en el arreglo (ver `/audio-mix`)
+
+## Jerarquía
+
+Tres niveles, y cada evento cae en uno:
+
+| Nivel | Qué entra | Puede interrumpir |
+|---|---|---|
+| **Ambiental** | Hover, navegación, toggle | Nada. Se pierde y no importa |
+| **Confirmatorio** | Tap, confirmación, éxito | Nada, pero no se debe perder |
+| **Crítico** | Error, alerta, timeout | Duckea el resto |
+
+Solo el nivel crítico duckea. Si los tres duckean, la música desaparece cada vez que el usuario navega un menú.
+
+## Haptics
+
+Cuando hay haptics, audio y vibración son **un solo evento percibido**. Reglas:
+
+- **Sincronía dura:** un desfasaje mayor a ~30 ms se percibe como dos eventos separados
+- **No duplicar la información:** si el haptic ya comunica la intensidad, el audio no necesita subir de nivel
+- **Complementariedad de banda:** el haptic cubre lo que el speaker chico no puede dar (el sub). Diseñar el audio sin depender del grave si hay haptic
+- **Respetar el ajuste del usuario:** haptics desactivado no debe dejar el evento sin feedback
+
+## Plataforma
+
+### Móvil — sesiones de audio
+
+Ignorar la sesión de audio es el bug más común de audio en móvil: la app pierde el audio en una llamada y no lo recupera nunca.
+
+| iOS `AVAudioSession` | Comportamiento |
+|---|---|
+| `.ambient` | Se mezcla con otro audio; el switch de silencio lo silencia |
+| `.playback` | Interrumpe otro audio; ignora el switch de silencio |
+| `.playAndRecord` | Para apps con voz |
+| `.soloAmbient` | Default; silencia otro audio |
+
+En Android el equivalente es AudioFocus. En los dos casos hay que manejar **interrupciones** (llamada, alarma) y **cambios de ruta** (auriculares conectados/desconectados).
+
+**Un juego que suena en background o que ignora el switch de silencio es un rechazo de store esperando pasar.** Para un juego, `.ambient` o `.soloAmbient` según si querés dejar que el usuario escuche su música.
+
+### Respetar el volumen del sistema
+
+Nunca normalizar por encima del volumen del sistema ni forzar un mínimo. Si el usuario bajó el volumen, bajó el volumen.
+
+## Accesibilidad
+
+- El sonido de UI **nunca puede ser el único canal** de información crítica: siempre acompañado de señal visual
+- Éxito y error tienen que distinguirse por **contorno melódico** (ascendente vs descendente), no solo por timbre — es lo que sobrevive a pérdida de agudos
+- Ofrecer control de volumen de UI separado de música y SFX
+- Los sonidos repetitivos de navegación tienen que poder desactivarse sin perder el feedback crítico
+
+---
+
+## Proceso
+
+1. **Listar los eventos** de UI reales y asignar cada uno a un nivel de jerarquía
+2. **Especificar** duración, carácter y nivel por evento, contra la tabla de referencia
+3. **Verificar la jerarquía** — hover y crítico tienen que ser inconfundibles
+4. **Definir haptics** si aplica, con sincronía y reparto de banda
+5. **Definir el manejo de sesión** en móvil
+6. **Chequear accesibilidad** — contorno melódico, canal redundante, controles separados
+7. **Escribir** — preguntar "¿Escribo el set a `<path>`?" antes de usar Write
+
+---
+
+## Verdict
+
+- **READY** — cada evento tiene nivel, duración y jerarquía; la accesibilidad está cubierta; en móvil la sesión de audio está definida
+- **CONCERNS** — el set existe pero no hay jerarquía diferenciada, o el nivel está por encima de −18 dB, o falta el manejo de interrupciones
+- **BLOCKED** — no está definida la lista de eventos de UI o falta la dirección del audio bible
+
+## Anti-patterns
+
+> → Read references/anti-patterns.md
+
+## Next steps
+
+- `/audio-mix` para el bus de UI y el ducking del nivel crítico
+- `/audio-spec` para formalizar cooldowns (navegación rápida spamea el evento)
+- `/audio-audit` para verificar niveles medidos contra los especificados