claude-code-arcane 2.0.0 → 2.2.0

package/skills/pdf-generator/scripts/render_body.py

@@ -27,6 +27,8 @@ Block types:
 Exit codes: 0 success, 1 bad args/missing file, 2 missing dep, 3 render error
 """
 
+from __future__ import annotations
+
 import argparse
 import io
 import json

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/review-dump/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: review-dump
+description: "Procesa el dump del dia en el vault: clasifica item por item con confirmacion, actualiza hub files, rutea tareas a su nota y crea el daily con la sintesis. Triggers: review dump, procesar el dump, cerrar el dia, revisar el inbox, clasificar lo que capture, crear el daily."
+argument-hint: "[today | YYYY-MM-DD]"
+category: "pkm"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit
+---
+
+# Review Dump - Clasificar el día
+
+Convertís el dump crudo en estructura. Es la sesión donde el vault se ordena, y la única del ciclo diario que escribe en varios lugares: por eso va item por item, con confirmación, y nunca en batch silencioso.
+
+Día a procesar: `$ARGUMENTS` (default: hoy)
+
+Aplica la rule `vault-conventions`.
+
+**Rutas por rol:** los destinos se nombran por rol y la ruta real de cada uno sale del `## Rutas` del `CLAUDE.md` del vault. Los defaults entre paréntesis solo aplican si el vault no declara otra cosa.
+
+## Fase 1 - Preparación
+
+1. **Ubicar el vault** (`--vault`, env `OBSIDIAN_VAULT`, o directorio actual con `.obsidian/`) y leer su `CLAUDE.md`: de ahí salen la estructura real, el contrato de frontmatter y los plugins disponibles. Si no hay `CLAUDE.md`, ofrecer `/second-brain adopt` y parar.
+2. **Verificar git.** Si el vault es un repo y el árbol está sucio, avisarlo antes de escribir: esta corrida toca varias notas y git es el undo.
+3. **Leer el dump** `<inbox>/YYYY-MM-DD dump.md` (default `_inbox/`), aceptando también el nombre sin sufijo si el vault viene de antes. Si no existe, decirlo y ofrecer `/brain-dump`. Si ya existe el daily de ese día, avisar que se va a actualizar y no duplicar secciones.
+4. **Inventariar el vault una sola vez**, desde el índice cacheado y no con `Glob`:
+
+   ```bash
+   python .claude/skills/vault-recall/scripts/vault_index.py "<vault>" inventory --format text
+   ```
+
+   Devuelve hubs con sus alias, proyectos, areas, los dumps sin daily y las fechas del último weekly y monthly. Es lo que necesitás para proponer destinos reales, y su costo no crece con el vault: un `Glob` de cuatro carpetas sobre miles de notas mete un listado enorme en contexto en cada corrida. Si el vault usa otra estructura, pasar `--role nombre=ruta` con lo que diga el contrato. Sin el script, `Glob` de los roles `hubs`, `projects`, `areas` y `atomic`.
+
+## Fase 2 - Clasificación item por item
+
+Para cada línea del dump, proponer un destino y esperar confirmación. Una línea por propuesta, agrupando las obvias para no hacer 30 preguntas:
+
+| Lo que es | Destino |
+|---|---|
+| Tarea de un proyecto existente | La nota del proyecto en `<projects>` (default `01_Projects/`) |
+| Tarea del día sin proyecto | Se queda en el dump |
+| Idea que se sostiene sola | Nota atómica nueva en `<atomic>` (default `03_Resources/`), delegar a `/zettel` |
+| Mención de una entidad con hub existente | Entrada en `## Historial` de ese hub |
+| Mención de una entidad recurrente sin hub | Proponer hub nuevo (delegar a `/hub-note`) |
+| URL para leer después | Se queda en el dump, o `/vault-clip` si el usuario lo quiere ahora |
+| Ruido, duplicado, ya resuelto | Nada: se deja en el dump y se marca resuelto |
+
+**Taxonomía de la captura.** Antes de decidir destino, clasificá qué **tipo** de captura es. Adaptado del patrón de organización por tipo en vez de por tema: el tema crea silos (una nota de psicología de la atención y una de por qué el contenido corto rinde nunca se cruzan), el tipo crea colisiones, y las colisiones son de donde sale lo original.
+
+| Tipo | Qué es | Suele terminar en |
+|---|---|---|
+| observación | algo que noté, sin conclusión todavía | dump, o `atomic` si se sostiene sola |
+| reacción | mi respuesta honesta a algo que leí o escuché | dump, o `## Historial` del hub del tema |
+| patrón | el mismo principio apareciendo en dos dominios distintos | casi siempre `atomic`: es la materia prima del conocimiento |
+| pregunta | algo que genuinamente no sé | dump, y al weekly como hilo abierto |
+| número | un dato concreto, con su fuente | hub del tema, o `atomic` si el número prueba algo |
+
+**Afilado.** Cada item que se mueve del dump se reescribe en una línea que se entienda sola: si todavía necesita explicación, no está afilada. "las notas sin links no se encuentran" es flojo; "una nota sin link entrante es invisible desde el día que se escribe" se sostiene sin contexto. El afilado se muestra al usuario para que confirme, porque es su idea y sus palabras.
+
+Reglas de la clasificación:
+
+- **Proponé, no decidas.** Cada movimiento se confirma. Si el usuario dice que no, el item se queda en el dump: quedarse es un destino válido y no es un fracaso.
+- **Una entidad merece hub cuando aparece en tres dumps distintos**, no la primera vez. Antes de eso es una mención, no un tema.
+- **Una idea merece nota atómica cuando el usuario podría querer linkearla desde otra cosa.** Si solo tiene sentido dentro del día en que se escribió, se queda en el dump.
+- No inventes destinos: las carpetas y los hubs propuestos tienen que existir en el inventario, o crearse explícitamente.
+
+## Fase 3 - Tareas
+
+Aplicar la regla de arrastre sin excepción:
+
+1. Buscar tareas abiertas en los dumps de días anteriores (últimos 7 días alcanza).
+2. Las que sigan abiertas se marcan `- [-]` (canceladas) **en su día original**, con el motivo si el usuario lo dice. No se mueven.
+3. Si la tarea sigue vigente, se crea de nuevo: en la nota del proyecto si tiene uno, o en el dump de hoy.
+4. Si hay plugin `obsidian-tasks-plugin`, usar su sintaxis de fecha y prioridad; si no, checkbox plano. No mezclar.
+
+Verdict de esta fase: PASS cuando ninguna tarea quedó duplicada entre un día viejo y el nuevo.
+
+## Fase 4 - Escribir
+
+Con approval sobre lo recolectado, en este orden:
+
+1. Notas atómicas nuevas y hubs nuevos (para que existan antes de que algo los linkee).
+2. Actualización de hubs existentes: entrada en `## Historial`, y reescritura de `## Estado actual` solo si cambió de verdad.
+3. Tareas en las notas de proyecto.
+4. El daily en `<daily>/YYYY-MM-DD.md` (default `Reflect/Daily/`) desde `<templates>/Daily.md`: link al dump, síntesis de 3 a 5 líneas, links a las notas creadas, y el estado real de las tareas del día.
+5. El dump queda como está, salvo las marcas de tarea. **El dump no se borra ni se vacía nunca:** es el registro crudo de lo que pasó ese día.
+
+Los links van hacia arriba: el daily linkea al dump y a las notas creadas; ninguna nota atómica linkea de vuelta al daily.
+
+## Fase 5 - Cierre
+
+1. **Reescribir `hot.md`** en la raíz del vault (desde `Templates/hot.md` la primera vez): dónde está el usuario, las notas que cambiaron con un link cada una, los hilos abiertos y las tareas vivas. Techo de 40 líneas, sin secretos, sin transcripciones crudas, y ninguna afirmación sin su link. **Se reescribe completo, no se le agrega al final.** Es el archivo que hace que la próxima sesión abra sabiendo dónde estabas, y es descartable: si contradice a una nota, la nota gana.
+2. Reportar en una tabla qué se creó, qué se actualizó y qué quedó en el dump.
+3. La sección `## Reflexión` del daily queda vacía: la escribe el usuario. No la completes ni la sugieras.
+4. Si el vault es un repo git, recordar el commit.
+
+Review COMPLETE cuando existe el daily, `hot.md` refleja el estado de hoy, los hubs tocados quedaron consistentes y ninguna tarea quedó duplicada.
+
+## Reglas
+
+- Escribir los hechos, no interpretarlos: la síntesis dice qué pasó, no qué significa.
+- Idempotente: correr el review dos veces sobre el mismo día no duplica entradas de historial ni secciones del daily.
+- Nunca borrar contenido del dump.
+- Sin guiones largos en nada de lo que escribas.
+- Si el dump tiene más de 40 items, proponer procesar por bloques temáticos en vez de item por item, y decir por qué.
+
+## Handoff
+
+Con el daily listo, el siguiente paso depende del día: durante la semana volver a `/brain-dump`, y al cierre `/review-weekly` para extraer los temas de la semana. Si la corrida dejó varias entidades sin hub o varias ideas sin nota, `/hub-note` y `/zettel` son los pasos puntuales.

package/skills/review-monthly/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: review-monthly
+description: "Retrospectiva mensual del vault: lee los weeklies del mes, detecta patrones que no se ven en una semana, registra logros con evidencia y deja semillas para el mes siguiente. Triggers: review mensual, cerrar el mes, retrospectiva del mes, monthly review, patrones del mes."
+argument-hint: "[current | YYYY-MM]"
+category: "pkm"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit
+---
+
+# Review Monthly - Cerrar el mes
+
+El nivel más alto del ciclo. El daily registra, el weekly detecta temas, el monthly detecta lo que ninguna semana sola muestra: qué avanzó de verdad, qué se repite sin moverse y qué merece atención el mes que viene.
+
+Mes a procesar: `$ARGUMENTS` (default: el mes en curso)
+
+Aplica la rule `vault-conventions`.
+
+**Rutas por rol:** los destinos se nombran por rol y la ruta real de cada uno sale del `## Rutas` del `CLAUDE.md` del vault. Los defaults entre paréntesis solo aplican si el vault no declara otra cosa.
+
+## Fase 1 - Leer el mes
+
+1. **Ubicar el vault** y leer su `CLAUDE.md`.
+2. **Leer los weeklies del mes (rol `weekly`).** Los weeklies son la fuente: no releas los dailies ni los dumps, ese trabajo ya está hecho y releerlo quema contexto sin agregar nada. Si faltan weeklies, listarlos y ofrecer `/review-weekly` para esas semanas antes de seguir.
+3. **Correr `/vault-audit`** para tener las métricas de salud del vault del mes (huérfanas, notas stale, semillas que no crecieron, notas `contested`, tareas viejas abiertas). El monthly es el momento natural del ciclo para mirarlas.
+4. **Presupuesto de lectura:** los weeklies del mes más el reporte del audit. Techo de 15 lecturas. Si faltan weeklies, se listan y se para: un monthly sobre dailies crudos cuesta diez veces más y sale peor.
+
+## Fase 2 - Extraer
+
+1. **Patrones:** lo que se repite a lo largo de varias semanas. Distinto de un tema semanal: un patrón es un tema que sobrevivió al mes.
+2. **Logros:** lo que efectivamente se cerró, cada uno con link a la nota que lo respalda. Sin evidencia linkeable no es un logro, es una impresión.
+3. **Lo que no se movió:** proyectos abiertos sin actividad en el mes, hilos que siguen abiertos desde la primera semana. Se nombran.
+4. **Semillas:** lo que apareció este mes y merece seguimiento, con el link a donde apareció.
+5. **Salud del vault:** las tres o cuatro métricas del audit que cambiaron respecto del mes anterior, si hay un monthly previo para comparar.
+6. **Contradicciones sin resolver:** las notas que el audit reporta como `contested`, cada una con el bloque `> [!warning] Contradicción sin resolver` que trae las dos posiciones y su fuente (mismo formato que usa `/review-weekly`). No las resuelvas: mostralas, con desde cuándo están abiertas. Que el vault te avise cuándo se contradice consigo mismo es una función, no un defecto. Si el usuario resuelve una en el momento, la resolución es una nota atómica nueva que linkea a las dos, y recién ahí se les saca el `contested`.
+
+## Fase 3 - Escribir
+
+Con approval sobre lo extraído, crear `<monthly>/YYYY-MM.md` (default `Reflect/Monthly/`) desde `<templates>/Monthly.md`, con links a los weeklies del mes. Si ya existe, actualizarlo sin duplicar secciones.
+
+Los links van hacia arriba: el monthly linkea a los weeklies y a las notas que respaldan los logros. No se edita ningún weekly desde acá.
+
+La sección `## Reflexión` queda vacía para el usuario.
+
+Review COMPLETE cuando existe el monthly con patrones, logros con evidencia y el estado de salud del vault.
+
+## Reglas
+
+- Un logro sin link no se escribe.
+- Lo que no avanzó se reporta con el mismo detalle que lo que avanzó.
+- Sin coaching: no proponés objetivos ni planes de mejora salvo que el usuario los pida.
+- Idempotente: correrlo dos veces sobre el mismo mes no duplica nada.
+- Sin guiones largos.
+
+## Handoff
+
+Con el monthly listo, si el audit reportó problemas el siguiente paso es `/vault-tidy` para aplicar los arreglos con approval. Si el mes dejó semillas que ya son ideas formadas, `/zettel`. Si no, se vuelve al ciclo diario con `/brain-dump`.

package/skills/review-weekly/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: review-weekly
+description: "Retrospectiva semanal del vault: lee los dumps y dailies de la semana, extrae temas recurrentes e hilos abiertos, cuenta tareas hechas y no hechas, y crea el weekly. Triggers: review semanal, cerrar la semana, retrospectiva de la semana, weekly review, que paso esta semana."
+argument-hint: "[current | YYYY-Www | YYYY-MM-DD]"
+category: "pkm"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit
+---
+
+# Review Weekly - Cerrar la semana
+
+Subís un nivel de abstracción: el daily registra, el weekly detecta patrones. Lo que buscás son los temas que se repitieron y los hilos que quedaron abiertos, no un resumen de siete resúmenes.
+
+Semana a procesar: `$ARGUMENTS` (default: la semana en curso, lunes a domingo)
+
+Aplica la rule `vault-conventions`.
+
+**Rutas por rol:** los destinos se nombran por rol y la ruta real de cada uno sale del `## Rutas` del `CLAUDE.md` del vault. Los defaults entre paréntesis solo aplican si el vault no declara otra cosa.
+
+## Fase 1 - Leer la semana
+
+1. **Ubicar el vault** y leer su `CLAUDE.md`.
+2. **Resolver el rango**: si el argumento es una fecha, la semana ISO que la contiene; si es `YYYY-Www`, esa; si no hay argumento, la semana en curso.
+3. **Leer los dailies del rango (rol `daily`) y sus dumps (rol `inbox`).** Los dailies dan la síntesis, los dumps dan lo que no llegó a la síntesis. Faltan dailies casi siempre: anotá qué días quedaron sin procesar y ofrecé `/review-dump` para esos días antes de seguir, porque un weekly sobre dumps crudos es peor.
+4. **Presupuesto de lectura:** los 7 dailies del rango, sus dumps, y hasta 10 hubs de los que esos dailies linkean. Techo duro de 25 lecturas. Si el material no alcanza para sacar conclusiones, **decilo y pará** en vez de entregar un weekly a medias con cara de completo.
+
+## Fase 2 - Extraer
+
+1. **Temas:** de 3 a 5 asuntos que aparecen en dos días o más. Cada tema con los dailies donde aparece. Un tema que aparece un solo día no es un tema, es un evento.
+
+Una conexión califica solo si es de uno de estos cuatro tipos (rúbrica adaptada del patrón de sesiones de conexión):
+
+| Tipo | Qué buscar |
+|---|---|
+| **A** | El mismo principio en dos dominios distintos |
+| **B** | Dos notas que se contradicen y la contradicción es productiva |
+| **C** | Un patrón que solo aparece juntando tres notas o más, y todavía no tiene nombre |
+| **D** | Una pregunta de una nota que otra nota responde sin proponérselo |
+
+Para no depender solo de lo que recordás de la semana, pedile candidatos al índice: `vault_index.py "<vault>" related "<nota de la semana>"` devuelve las notas más cercanas por vocabulario compartido, y ahí suelen estar las del tipo A y C. El criterio de si califican sigue siendo tuyo: el script propone vecinos, no conexiones.
+
+**Si la conexión es obvia, no califica.** El test es: ¿el usuario la habría encontrado solo, eventualmente? Si sí, sobra. Este paso se gana el lugar encontrando lo que él se pierde. Mínimo 3, máximo 5: por encima de eso la lista deja de leerse.
+
+Las del tipo B se marcan: las dos notas involucradas van al weekly como contradicción, y si el usuario confirma que sigue sin resolverse, se les pone `status: contested` en el frontmatter con approval. La contradicción se preserva, no se resuelve sola.
+
+### El artefacto de una contradicción
+
+Cuando una conexión tipo B se confirma, el weekly lleva un bloque con **las dos posiciones enfrentadas y su fuente**, no una síntesis que las promedie:
+
+```markdown
+> [!warning] Contradicción sin resolver
+> **[[Nota A]]** dice: <la afirmación, textual o parafraseada fielmente>
+> **[[Nota B]]** dice: <la otra>
+> Sin resolver desde YYYY-MM-DD. Las dos quedan `status: contested`.
+```
+
+Se usa `[!warning]` con título propio y no `[!contradiction]`: ese tipo no existe en Obsidian y renderizaría como un `note` cualquiera sin avisar (ver `/obsidian-markdown`).
+
+Tres reglas del artefacto:
+
+- **No la resuelvas.** Si te parece obvio cuál de las dos gana, decilo como comentario aparte; la nota no elige.
+- **No borres ninguna de las dos.** Una contradicción resuelta borrando la mitad no se resolvió, se tapó.
+- **Cuando el usuario la resuelve**, se le saca el `contested` a las dos y la resolución va como nota atómica propia, linkeando a ambas. Eso es conocimiento nuevo: es el caso donde la contradicción produjo algo.
+2. **Hilos abiertos:** preguntas o decisiones pendientes, distintas de una tarea. "Definir si migramos" es un hilo; "mandar el mail" es una tarea.
+3. **Tareas:** conteo de hechas y de no hechas, con las no hechas nombradas una por una. No suavizar el número ni omitirlas.
+4. **Notas que crecieron:** hubs y notas atómicas que recibieron contenido en la semana.
+5. **Señales, si aparecen:** un tema que se repite tres semanas seguidas sin avanzar, o un proyecto sin una sola mención en toda la semana. Reportarlas como observación, sin diagnóstico ni consejo.
+
+## Fase 3 - Escribir
+
+Refrescar también `hot.md` con los hilos abiertos de la semana, respetando su techo de 40 líneas.
+
+Con approval sobre lo extraído, crear `<weekly>/YYYY-Www.md` (default `Reflect/Weekly/`) desde `<templates>/Weekly.md`, con links a los dailies de la semana. Si el weekly ya existe, actualizarlo sin duplicar secciones.
+
+Los links van hacia arriba: el weekly linkea a los dailies. Ningún daily se edita para linkear al weekly.
+
+La sección `## Reflexión` queda vacía para el usuario.
+
+Review COMPLETE cuando existe el weekly con temas, hilos y el conteo real de tareas.
+
+## Reglas
+
+- Sin interpretación: reportás lo que pasó y lo que se repitió, no qué significa ni qué debería hacer el usuario.
+- Las tareas no hechas se nombran. Un weekly que las esconde no sirve para nada.
+- Idempotente: correrlo dos veces sobre la misma semana no duplica nada.
+- Solo el rango de la semana: nunca reescribir dailies ni dumps pasados desde acá.
+- Sin guiones largos.
+
+## Handoff
+
+Con el weekly listo, el siguiente paso es seguir con `/brain-dump` la semana que viene, y al cierre del mes `/review-monthly`, que lee los weeklies y no los dailies. Si el weekly dejó al descubierto un tema que ya merece nota propia, `/zettel` o `/hub-note`.