claude-code-arcane 2.0.0 → 2.2.0

package/skills/audio-audit/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: audio-audit
+description: "Auditoria de audio: voice count, CPU, memoria, streaming, compliance de loudness (ASWG-R001), conformidad de assets contra spec y checklist por plataforma. Usar para: QA de audio, performance de audio, verificar loudness, revisar assets, pre-certificacion."
+category: "audio"
+argument-hint: "[full | perf | loudness | assets | platform]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit, Bash
+---
+# audio-audit — QA y Compliance de Audio
+
+Verifica que el audio del proyecto cumple: performance dentro del presupuesto, assets conformes al spec, y loudness dentro del target de plataforma.
+
+## Cuándo usar
+
+- Antes de una milestone o de certificación
+- El audio se corta, se satura o come demasiado CPU
+- Verificar assets entregados por un contractor
+- Auditar loudness para cumplir requisitos de plataforma
+- Después de integrar un sistema nuevo, para medir su costo real
+
+## Input
+
+1. Leer audio bible (sección 8, standards) y los specs de `/audio-spec`
+2. Determinar plataformas target, y cuál es la más baja
+3. Preguntar al usuario: alcance (`full` / solo perf / solo loudness / solo assets) y si hay captura de profiler disponible
+
+---
+
+## 1. Performance
+
+**Presupuesto:** el audio dispone del **5-10% del frame time**. A 60 fps el frame son 16.6 ms, así que el audio tiene ~0.8-1.7 ms. A 90 fps (VR) el frame son ~11 ms y el margen es menor.
+
+| Métrica | Cómo se mide | Verdict |
+|---|---|---|
+| **CPU de audio** | Profiler del middleware, en gameplay real | FAIL si supera el 10% del frame sostenido |
+| **Voces activas** | Pico vs límite configurado | CONCERNS si el pico toca el límite; FAIL si hay descartes de sonidos de prioridad alta |
+| **Memoria de audio** | Por bank y total, vs budget del proyecto | FAIL si supera el budget en la plataforma más baja |
+| **Accesos de streaming** | Contador de streaming del profiler | CONCERNS si hay starvation |
+| **Game objects registrados** | Contador, medido a lo largo de una sesión larga | FAIL si crece monótonamente (leak) |
+
+**Medir en gameplay real, no en el editor.** El editor dispara eventos en orden, uno por vez, sin ruido. El jugador produce combinaciones que nadie planificó. Y medir en la **plataforma más baja** del target: el presupuesto que cierra en PC no dice nada de un handheld.
+
+**El leak de game objects es el hallazgo más frecuente.** Si el contador de objetos registrados crece durante una sesión de dos horas y nunca baja, hay des-registros faltantes. Se ve solo en sesiones largas.
+
+### Costos de referencia
+
+Para saber si un número medido es razonable:
+
+| Operación | Costo esperado por fuente |
+|---|---|
+| Convolución HRTF (512 taps) | ~2 ms |
+| Encode ambisónico | ~0.1 ms |
+| Decode ambisónico a binaural | ~1 ms total |
+| Footstep procedural | ~1-2 ms |
+| Síntesis de viento | ~0.5 ms/frame |
+| Panning + atenuación | despreciable |
+
+Si lo medido se desvía mucho del esperado, la causa suele ser configuración (más taps, más fuentes espacializadas de las previstas) antes que el motor.
+
+## 2. Loudness
+
+Referencia de industria en juegos: **ASWG-R001** (Sony), la única especificación publicada por una plataforma mayor.
+
+| Contexto | Loudness promedio | True peak máximo |
+|---|---|---|
+| Consola / home | **−23 LUFS** (±2) | **−1 dBTP** |
+| Portable / handheld | **−18 LUFS** | −1 dBTP |
+
+**Cómo medir bien:**
+
+- Se mide el **programa completo en gameplay representativo**, no un asset aislado. Medir un `.wav` no dice nada sobre cumplimiento
+- Sesión de duración suficiente para promediar: al menos varios minutos cubriendo exploración, combate y diálogo
+- Medir el **true peak**, no el peak de sample: la codificación lossy puede generar picos por encima del valor medido en PCM
+- **Confirmar el target vigente** de cada plataforma antes de certificación. Las recomendaciones se revisan — el promedio de ASWG también se citó como −24 LKFS, así que no confiar en un número memorizado
+
+**Verdict:** COMPLIANT dentro del target con su tolerancia; NON-COMPLIANT fuera, o con true peak por encima de −1 dBTP.
+
+## 3. Conformidad de assets
+
+Verificación mecánica contra los standards del bible. Esto se automatiza:
+
+| Chequeo | Falla típica |
+|---|---|
+| Sample rate | Mezcla de 44.1 y 48 kHz en el mismo proyecto |
+| Bit depth | 24-bit donde el pipeline espera 16 |
+| Canales | Estéreo en un asset que se usa como fuente 3D mono |
+| Naming | No sigue el patrón; rompe batch y automatización de banks |
+| DC offset | Produce clicks al concatenar |
+| Silencio al inicio | Retrasa el ataque; se percibe como lag |
+| Clipping | Picos a 0 dBFS en el asset crudo |
+| Duración vs spec | Fuera del rango especificado |
+| Loudness por categoría | Assets de la misma categoría con niveles dispares |
+
+**Fuente 3D en estéreo es el hallazgo más común y el más silencioso:** el middleware la trata distinto o la colapsa, y la localización espacial se degrada sin que nadie vea un error.
+
+La skill trae el verificador: `scripts/check_assets.py`, stdlib-only (módulo `wave`), recursivo sobre una carpeta.
+
+```bash
+python skills/audio-audit/scripts/check_assets.py assets/audio \
+  --rate 48000 --bits 16 --mono-3d --naming '^(sfx|vo|mus)_'
+```
+
+Chequea sample rate, bit depth, canales, naming, clipping, DC offset, silencio inicial, archivos vacíos o silenciosos, y avisa cuando el sample rate obliga a un resampleo costoso. Emite `[FAIL]` / `[WARN]` / `[SKIP]` por hallazgo y cierra con COMPLIANT / CONCERNS / NON-COMPLIANT; exit code 1 solo si hay FAIL, para usarlo en CI.
+
+Lo que necesita una herramienta externa (loudness integrado, análisis espectral) se reporta como `[SKIP]` en vez de abortar la corrida.
+
+## 4. Checklist por plataforma
+
+| Ítem | Aplica a |
+|---|---|
+| Loudness dentro del target del contexto | Todas |
+| True peak ≤ −1 dBTP | Todas |
+| Manejo de interrupciones (llamada, alarma) | Móvil |
+| Manejo de cambio de ruta (auriculares) | Móvil, consola |
+| Respeto del switch de silencio | iOS |
+| Comportamiento en background | Móvil |
+| Mezcla con audio de terceros | Móvil |
+| Audio no rompe al perder foco | Todas |
+| Memoria dentro del budget de la plataforma | Todas |
+| Se puede mutear todo desde opciones | Todas |
+| Controles separados: música / SFX / voz / UI | Todas |
+| Información crítica no exclusivamente por audio | Todas (accesibilidad) |
+| Subtítulos para todo el diálogo | Todas (accesibilidad) |
+
+El comportamiento en background y el switch de silencio en iOS son causas concretas de rechazo de store, no recomendaciones.
+
+---
+
+## Proceso
+
+1. **Determinar el alcance** y la plataforma más baja del target
+2. **Capturar** con el profiler del middleware en gameplay representativo, no en el editor
+3. **Medir performance** contra el presupuesto y comparar con los costos de referencia
+4. **Medir loudness** del programa completo, con true peak
+5. **Verificar assets** contra los standards, automatizado si el volumen lo justifica
+6. **Recorrer el checklist** de plataforma
+7. **Reportar** con severidad por hallazgo y, si el usuario lo pide, preguntar "¿Escribo el reporte a `<path>`?" antes de usar Write
+
+### Formato del reporte
+
+Por hallazgo: qué se midió, valor medido, valor esperado, severidad, y dónde está el problema. Un hallazgo sin número medido no es un hallazgo, es una impresión.
+
+---
+
+## Verdict
+
+Global, y por sección:
+
+- **COMPLIANT** — performance dentro del presupuesto en la plataforma más baja, loudness dentro del target, assets conformes, checklist completo
+- **CONCERNS** — hay desvíos que no bloquean: pico de voces tocando el límite, assets con naming inconsistente, loudness en el borde de la tolerancia
+- **NON-COMPLIANT** — CPU o memoria fuera de presupuesto, loudness fuera del target, leak de game objects, o un ítem de checklist que es causa de rechazo de plataforma
+
+Un NON-COMPLIANT en cualquier sección bloquea certificación.
+
+## Anti-patterns
+
+> → Read references/anti-patterns.md
+
+## Next steps
+
+- `/spatial-audio` si el costo de espacialización está fuera de presupuesto
+- `/audio-mix` si el problema es loudness o balance entre categorías
+- `/middleware-integration` si hay leaks, banks mal organizados o descartes de voces
+- `/procedural-audio` si la memoria no cierra por cantidad de samples

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

@@ -0,0 +1,65 @@
+# Audio Audit — Anti-patterns
+
+## Medir en el editor
+
+El editor dispara eventos en orden, uno por vez, sin ruido de fondo. El jugador produce combinaciones que nadie planificó. Las mediciones del editor no predicen nada.
+
+## Medir en la plataforma más alta
+
+El presupuesto cierra cómodo en PC y revienta en el handheld. La auditoría se hace contra el piso del target.
+
+## Medir loudness de un asset
+
+Los targets de LUFS son del programa completo en gameplay representativo. Medir un `.wav` no dice nada sobre cumplimiento.
+
+## Sesión de medición demasiado corta
+
+Treinta segundos de exploración tranquila da un LUFS que no representa el juego. La medición tiene que cubrir exploración, combate y diálogo.
+
+## Confiar en un target memorizado
+
+Las recomendaciones de plataforma se revisan. Confirmar el vigente antes de certificación.
+
+## Medir peak de sample en vez de true peak
+
+Un mix que llega a 0 dBFS en PCM puede generar picos por encima al codificarse en lossy. El −1 dBTP existe justamente por eso.
+
+## No buscar leaks
+
+El contador de game objects registrados que crece durante dos horas y nunca baja es el hallazgo más frecuente, y solo se ve en sesiones largas. Una prueba de cinco minutos no lo encuentra.
+
+## Aceptar el pico de voces al límite
+
+Si el pico toca el límite configurado, cualquier situación un poco peor empieza a descartar sonidos. Y si lo que se descarta es feedback de la acción del jugador, el juego se siente roto sin ningún error visible.
+
+## Ignorar qué se descarta
+
+El número de descartes por sí solo no dice nada. Lo que importa es la prioridad de lo descartado: perder un ambiente lejano está bien, perder el disparo del jugador no.
+
+## Fuente 3D en estéreo
+
+El hallazgo más silencioso: el middleware la colapsa o la trata distinto, y la localización espacial se degrada sin que aparezca ningún error. Verificar canales por categoría de uso.
+
+## Mezcla de sample rates
+
+44.1 y 48 kHz en el mismo proyecto obliga a resampleo en runtime, que cuesta CPU y puede introducir artefactos. Un solo sample rate por proyecto.
+
+## Silencio al inicio del asset
+
+Retrasa el ataque y se percibe como lag de input, aunque el código responda instantáneo. Se detecta automáticamente y casi nunca se busca.
+
+## Hallazgo sin número
+
+"El audio suena saturado" no es un hallazgo. Qué se midió, valor medido, valor esperado, dónde. Sin eso, nadie puede arreglarlo ni verificar que se arregló.
+
+## Auditar a mano miles de assets
+
+La conformidad de sample rate, canales, naming y duración es mecánica: se automatiza. La inspección manual de 4.000 archivos garantiza que algo se pase por alto.
+
+## Fallar cuando falta una herramienta externa
+
+Si el chequeo profundo necesita una herramienta que no está instalada, reportar `[SKIP]` y seguir. Abortar la auditoría entera por una dependencia opcional deja al usuario sin los chequeos que sí se podían correr.
+
+## Dejar el checklist de plataforma para el final
+
+El comportamiento en background y el switch de silencio en iOS son causas concretas de rechazo. Descubrirlos en certificación cuesta una release.

package/skills/audio-audit/scripts/check_assets.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""Verifica conformidad mecanica de assets WAV contra los standards del proyecto.
+
+Solo stdlib: usa el modulo `wave` para leer cabeceras y frames. Los chequeos que
+necesitarian una herramienta externa se reportan como [SKIP], no rompen la corrida.
+
+Uso:
+    python check_assets.py assets/audio
+    python check_assets.py assets/audio --rate 48000 --bits 16
+    python check_assets.py assets/audio --mono-3d --naming "^(sfx|vo|mus)_"
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import struct
+import sys
+import wave
+
+# Umbrales de deteccion. Explicitos para que se puedan discutir.
+LEADING_SILENCE_MS = 10.0    # silencio inicial que ya se percibe como lag
+SILENCE_FLOOR = 0.002        # ~-54 dBFS: por debajo se considera silencio
+DC_OFFSET_LIMIT = 0.01       # 1% de fondo de escala
+CLIP_SAMPLE_LIMIT = 3        # muestras en fondo de escala para llamarlo clipping
+
+
+class Finding:
+    __slots__ = ("path", "severity", "check", "detail")
+
+    def __init__(self, path: str, severity: str, check: str, detail: str):
+        self.path = path
+        self.severity = severity      # FAIL | WARN | SKIP
+        self.check = check
+        self.detail = detail
+
+
+def read_samples(handle: wave.Wave_read, limit: int | None = None) -> list[int]:
+    """Devuelve las muestras del primer canal, normalizadas a int con signo."""
+    width = handle.getsampwidth()
+    channels = handle.getnchannels()
+    frames = handle.getnframes() if limit is None else min(limit, handle.getnframes())
+    raw = handle.readframes(frames)
+
+    if width == 1:
+        # 8-bit WAV es unsigned; centrar en 0
+        values = [byte - 128 for byte in raw]
+    elif width == 2:
+        values = list(struct.unpack(f"<{len(raw) // 2}h", raw[: len(raw) // 2 * 2]))
+    elif width == 3:
+        values = []
+        for offset in range(0, len(raw) - 2, 3):
+            chunk = raw[offset:offset + 3]
+            value = int.from_bytes(chunk, "little", signed=True)
+            values.append(value)
+    elif width == 4:
+        values = list(struct.unpack(f"<{len(raw) // 4}i", raw[: len(raw) // 4 * 4]))
+    else:
+        return []
+
+    return values[::channels] if channels > 1 else values
+
+
+def full_scale(width: int) -> float:
+    return float(2 ** (8 * width - 1))
+
+
+def check_file(path: str, args: argparse.Namespace) -> list[Finding]:
+    findings: list[Finding] = []
+    name = os.path.basename(path)
+
+    if args.naming and not re.search(args.naming, name):
+        findings.append(Finding(path, "FAIL", "naming",
+                                f"no matchea {args.naming!r}"))
+
+    try:
+        with wave.open(path, "rb") as handle:
+            rate = handle.getframerate()
+            width = handle.getsampwidth()
+            channels = handle.getnchannels()
+            frames = handle.getnframes()
+            duration = frames / rate if rate else 0.0
+
+            if args.rate and rate != args.rate:
+                findings.append(Finding(path, "FAIL", "sample-rate",
+                                        f"{rate} Hz, se esperaba {args.rate} Hz"))
+            if args.bits and width * 8 != args.bits:
+                findings.append(Finding(path, "FAIL", "bit-depth",
+                                        f"{width * 8}-bit, se esperaba {args.bits}-bit"))
+            if args.mono_3d and channels != 1:
+                findings.append(Finding(
+                    path, "FAIL", "channels",
+                    f"{channels} canales; una fuente 3D tiene que ser mono o el "
+                    f"middleware la colapsa y se degrada la localizacion"))
+            if args.rate and rate and rate != args.rate and args.rate % rate and rate % args.rate:
+                findings.append(Finding(path, "WARN", "resample",
+                                        f"{rate} Hz no es multiplo ni divisor de "
+                                        f"{args.rate} Hz: el resampleo es mas costoso"))
+            if frames == 0:
+                findings.append(Finding(path, "FAIL", "empty", "0 frames"))
+                return findings
+            if args.max_duration and duration > args.max_duration:
+                findings.append(Finding(path, "WARN", "duration",
+                                        f"{duration:.2f} s > {args.max_duration:.2f} s"))
+
+            samples = read_samples(handle)
+            if not samples:
+                findings.append(Finding(path, "SKIP", "content",
+                                        f"{width * 8}-bit no soportado por el lector stdlib"))
+                return findings
+
+            scale = full_scale(width)
+            peak = max(abs(value) for value in samples)
+
+            clipped = sum(1 for value in samples if abs(value) >= scale - 1)
+            if clipped >= CLIP_SAMPLE_LIMIT:
+                findings.append(Finding(path, "FAIL", "clipping",
+                                        f"{clipped} muestras en fondo de escala"))
+
+            offset = sum(samples) / len(samples) / scale
+            if abs(offset) > DC_OFFSET_LIMIT:
+                findings.append(Finding(path, "WARN", "dc-offset",
+                                        f"{offset * 100:+.2f}% - produce clicks al concatenar"))
+
+            floor = SILENCE_FLOOR * scale
+            if peak < floor:
+                # Archivo enteramente silencioso: el chequeo de silencio inicial
+                # sobra, seria el mismo hallazgo dos veces.
+                findings.append(Finding(path, "FAIL", "silent", "el archivo es silencio"))
+                return findings
+
+            leading = 0
+            for value in samples:
+                if abs(value) > floor:
+                    break
+                leading += 1
+            leading_ms = leading / rate * 1000
+            if leading_ms > LEADING_SILENCE_MS:
+                findings.append(Finding(
+                    path, "WARN", "leading-silence",
+                    f"{leading_ms:.1f} ms de silencio inicial - se percibe como lag de input"))
+
+    except wave.Error as error:
+        findings.append(Finding(path, "SKIP", "format",
+                                f"no es un WAV PCM legible ({error})"))
+    except OSError as error:
+        findings.append(Finding(path, "FAIL", "io", str(error)))
+
+    return findings
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Verifica conformidad de assets WAV contra los standards del proyecto.")
+    parser.add_argument("root", help="carpeta a auditar (recursivo)")
+    parser.add_argument("--rate", type=int, help="sample rate esperado, ej 48000")
+    parser.add_argument("--bits", type=int, choices=(8, 16, 24, 32),
+                        help="bit depth esperado")
+    parser.add_argument("--mono-3d", action="store_true",
+                        help="exigir mono (assets usados como fuentes 3D)")
+    parser.add_argument("--naming", help="regex que el nombre de archivo debe matchear")
+    parser.add_argument("--max-duration", type=float,
+                        help="duracion maxima en segundos")
+    args = parser.parse_args(argv)
+
+    if not os.path.isdir(args.root):
+        print(f"[FAIL] no es una carpeta: {args.root}", file=sys.stderr)
+        return 1
+
+    paths = []
+    for directory, _subdirs, files in os.walk(args.root):
+        for name in sorted(files):
+            if name.lower().endswith(".wav"):
+                paths.append(os.path.join(directory, name))
+
+    if not paths:
+        print(f"[SKIP] no hay .wav en {args.root}")
+        return 0
+
+    findings: list[Finding] = []
+    for path in paths:
+        findings.extend(check_file(path, args))
+
+    fails = [f for f in findings if f.severity == "FAIL"]
+    warns = [f for f in findings if f.severity == "WARN"]
+    skips = [f for f in findings if f.severity == "SKIP"]
+
+    for group in (fails, warns, skips):
+        for finding in group:
+            relative = os.path.relpath(finding.path, args.root)
+            print(f"[{finding.severity}] {relative}: {finding.check} - {finding.detail}")
+
+    print()
+    print(f"{len(paths)} assets | {len(fails)} FAIL | {len(warns)} WARN | {len(skips)} SKIP")
+
+    if fails:
+        print("NON-COMPLIANT")
+        return 1
+    if warns:
+        print("CONCERNS")
+        return 0
+    print("COMPLIANT")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/audio-bible/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: audio-bible
+description: "Audio Bible authoring: sonic palette, emotional targets per game state, frequency allocation, mix hierarchy, audio standards. Usar para: direccion de audio, paleta sonora, identidad sonora del juego."
+category: "audio"
+argument-hint: "[full|core|standards]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit
+---
+# audio-bible — Sonic Identity Specification
+
+Define la identidad sonora del juego. Toda produccion de audio se gatea contra este documento — es el equivalente auditivo de `/art-bible`.
+
+## Cuándo usar
+
+- Después de tener game concept aprobado, antes de producir un solo sonido
+- Cuando necesitás estandarizar el criterio sonoro entre sound designers y compositores
+- Antes de escribir specs de SFX (`/audio-spec`) o diseñar el sistema de música (`/adaptive-music`)
+
+## Input
+
+1. Leer game concept (elevator pitch, pilares, core fantasy) y art bible si existe
+2. Preguntar al usuario: scope (full bible / core secciones 1-4 / solo standards), plataformas target, y referencias sonoras (juegos, films, discos)
+3. Si ya existe audio bible: detectar secciones completas vs vacías, trabajar solo las incompletas
+
+---
+
+## Secciones del Audio Bible
+
+### Core (secciones 1-4) — definen el lenguaje sonoro
+
+| # | Sección | Qué define | Criterio de calidad |
+|---|---------|-----------|-------------------|
+| 1 | **Sonic Identity Statement** | Regla sonora de 1 línea + 2-3 principios de soporte | Resuelve cualquier ambigüedad sonora. Cada principio ancla en un pilar del juego |
+| 2 | **Emotional Targets por Game State** | Qué debe sentir el jugador en exploración, combate, tensión, victoria, menú | Cada estado auditivamente distinto sin mirar la pantalla |
+| 3 | **Sonic Palette** | Fuentes y texturas: acústico vs sintético, orgánico vs procesado, época/lugar, vocabulario tímbrico | Un sonido nuevo se puede aceptar o rechazar leyendo esto |
+| 4 | **Frequency Allocation** | Qué categoría es dueña de qué banda — evita masking antes de que exista el mix | Diálogo, música, SFX y ambiente no compiten por la misma banda |
+
+### Production (secciones 5-8) — reglas concretas
+
+| # | Sección | Qué define |
+|---|---------|-----------|
+| 5 | **Mix Hierarchy** | Prioridad entre categorías, qué duckea a qué, qué nunca se pisa |
+| 6 | **Music Direction** | Instrumentación, escalas/modos, tempo range, rol del silencio, estrategia adaptativa |
+| 7 | **SFX Direction** | Filosofía de impacto, realismo vs estilización, tratamiento del feedback de UI, uso de variación |
+| 8 | **Audio Standards** | Sample rate, bit depth, formatos, naming, targets de loudness, budgets de memoria y voces por plataforma |
+
+### Reference (sección 9)
+
+| # | Sección | Qué define |
+|---|---------|-----------|
+| 9 | **References & Prohibitions** | 3-5 referencias con qué tomar y qué evitar de cada una. Prohibiciones sonoras explícitas |
+
+---
+
+## Frequency allocation — el punto que más se saltea
+
+La mayoría de los mixes de juego se rompen porque nadie asignó bandas antes de producir. Definir dueño primario por banda evita rehacer assets:
+
+| Banda | Dueño primario | Nota |
+|---|---|---|
+| Sub (20-60 Hz) | Impactos, explosiones | Reservado, no lo llenes de música |
+| Low (60-250 Hz) | Música (bajo, kick), body de impactos | Zona de masking más frecuente |
+| Low-mid (250-500 Hz) | Ambiente, body de props | Acumula barro si no se controla |
+| Mid (500 Hz-2 kHz) | **Diálogo** — intocable | El resto cede acá |
+| High-mid (2-6 kHz) | Feedback de UI, transientes, definición | Fatiga rápido; usar con precisión |
+| High (6-20 kHz) | Aire, detalle, brillo | Primero en irse en compresión lossy |
+
+Cuando un asset nuevo pelea una banda que no le corresponde, la solución es de diseño (cambiar la fuente), no de EQ.
+
+---
+
+## Proceso
+
+Para cada sección:
+1. **Draftar** basándose en game concept, pilares y referencias
+2. **Presentar** al usuario para review
+3. **Escribir** a archivo inmediatamente después de aprobación — preguntar "¿Escribo esta sección a `<path>`?" antes de usar Write
+
+No batchear — escribir cada sección aprobada antes de pasar a la siguiente.
+
+### Conflictos
+
+Si hay tensión entre dirección de audio y constraints técnicos (ej: música en stems para adaptatividad, pero el budget de memoria no da), surfacear el conflicto explícitamente con ambas posiciones. No resolver silenciosamente.
+
+Si la dirección sonora conflictúa con accesibilidad (ej: información crítica solo por audio), surfacear y dejar que el usuario decida.
+
+---
+
+## Principios
+
+- El audio bible es un **documento de restricción**: narrows solution space en favor de coherencia sonora
+- Cada sección debe conectar con los pilares del juego
+- Específico > genérico: "dark and tense" no alcanza — decir la emoción exacta, la fuente tímbrica, el rango de frecuencia, un elemento sonoro que carga el mood
+- Para cada referencia: qué tomar Y qué evitar
+- El silencio es una decisión de diseño, no la ausencia de una — documentarlo
+- Los standards deben ser producibles: un contractor externo debería poder entregar assets válidos sin briefing adicional
+
+---
+
+## Anti-patterns
+
+> → Read references/anti-patterns.md for common mistakes to avoid
+
+## Verdict
+
+Al cerrar el documento, emitir un verdict por sección:
+
+- **READY** — la sección resuelve ambigüedades y es accionable para producción
+- **CONCERNS** — está escrita pero es genérica o no ancla en pilares; listar qué falta
+- **BLOCKED** — falta input upstream (game concept, plataformas, budget) que no se puede inventar
+
+Si alguna sección Core (1-4) queda en BLOCKED, el bible no habilita producción todavía.
+
+## Next steps
+
+- `/audio-spec` para bajar la dirección a spec sheets de SFX y event lists
+- `/adaptive-music` para diseñar el sistema de música contra los emotional targets de la sección 2
+- `/audio-mix` para implementar la mix hierarchy de la sección 5
+- `/audio-audit` para verificar assets producidos contra los standards de la sección 8

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

@@ -0,0 +1,39 @@
+# Audio Bible — Anti-patterns
+
+## Dirección vacía
+
+**Síntoma:** "El juego suena oscuro e inmersivo."
+
+Cualquier sonido pasa ese filtro, así que no filtra nada. Una statement útil excluye: "Todo suena grabado dentro de una habitación de concreto — nada nace limpio, todo tiene el cuarto encima." Eso rechaza el 90% de una library.
+
+## Paleta sin fuentes
+
+Listar adjetivos (cálido, agresivo, etéreo) sin decir de dónde sale el sonido deja la decisión al sound designer, que es exactamente lo que el bible debería resolver. Nombrar fuentes: instrumentos, materiales, técnicas de grabación, cadenas de procesamiento.
+
+## Frequency allocation ausente
+
+Se produce todo, se llega al mix, y diálogo compite con música y SFX en 500 Hz-2 kHz. La solución tardía es EQ quirúrgico que adelgaza todo. La solución temprana es asignar bandas antes de producir.
+
+## Copiar la referencia entera
+
+"Suena como Hollow Knight" sin decir qué se toma produce pastiche. Para cada referencia: qué tomar y qué evitar explícitamente.
+
+## Emotional targets que no se distinguen
+
+Si exploración y tensión comparten instrumentación, tempo y densidad, el jugador no lee el estado por audio. Test: describir los estados sin nombrarlos y ver si son distinguibles.
+
+## Standards no producibles
+
+"Audio de alta calidad, sin artefactos" no es un standard. Sample rate, bit depth, formato por plataforma, naming pattern, target de loudness con tolerancia, headroom y budget de voces sí lo son.
+
+## El silencio sin documentar
+
+Los juegos con mejor audio usan silencio deliberadamente. Si el bible no dice dónde y por qué, alguien va a llenar cada segundo con ambiente.
+
+## Ignorar la plataforma
+
+Un bible que asume monitores de estudio falla en el speaker de un handheld o en earbuds bluetooth. Los targets de loudness y la allocation de frecuencias cambian por plataforma — documentar cuáles importan.
+
+## Bible que nadie gatea
+
+Si no hay un paso de review que compare assets contra el bible, es decoración. Conectarlo con `/audio-audit` y hacerlo condición de entrega.