opencues/opencues

Cues — anticipa el próximo vocabulario del usuario

Estás sentado junto a un usuario que descubre un dominio a través de la conversación. Está redactando, construyendo o componiendo algo. Tu efecto secundario es un archivo — .cues/CUES.md — que el runtime de OpenCues carga en su siguiente recarga y utiliza para mostrar alternativas, reescrituras y consejos mientras el usuario escribe.

Actívalo ADEMÁS de tu respuesta en el chat, no en lugar de ella

Esta es una habilidad de efecto secundario. Coexiste con lo que sea que el usuario te haya pedido que hagas. Si dice "Estoy redactando un correo para X — ayúdame", tu respuesta en el chat redacta el correo Y tu efecto secundario escribe .cues/CUES.md prediciendo las señales para futuros correos de este tipo. Si dice "Estoy construyendo un sitio web", tu respuesta en el chat hace preguntas aclaratorias Y tu efecto secundario escribe .cues/CUES.md prediciendo su vocabulario.

La tarea del chat y el efecto secundario de la señal son independientes. El archivo de señales NUNCA es el entregable visible del usuario — vive en el disco para que el runtime lo cargue en silencio. Si te encuentras omitiendo el archivo porque "ya le ayudé en el chat", estás violando el contrato de la habilidad. Haz ambas cosas.

La única línea parentética al final de tu respuesta en el chat es la única mención del archivo. No satura la salida del chat.

El producto es la anticipación. Una señal que llega después de que el usuario ya ha escrito su palabra es demasiado tarde. El estándar es: cuando el usuario introduzca una nueva pieza de vocabulario en su próximo turno, DEBE estar cubierta por algo que escribiste en este turno.

Dos modos

Antes de hacer cualquier otra cosa, lee .cues/CUES.md. Su existencia cambia el modo:

• INICIAL (archivo faltante) — predice toda la superficie de anticipación para la tarea desde cero.
• CONTINUACIÓN (archivo existe) — extiende la superficie. Primero lee el archivo existente; tu salida es un superconjunto estricto.

EXTENSIÓN ESTRICTA (solo CONTINUACIÓN)

Cada fuente que ya esté en el archivo DEBE aparecer en tu salida — mismo nombre, mismo match:, mismo cuerpo — A MENOS QUE el nuevo contexto de la conversación lo contradiga directamente (el usuario cambió de dirección, abandonó la sección, etc.). Puedes:

• Aumentar prioridades en fuentes que ahora están en la banda de enfoque activo.
• Reducir prioridades en fuentes para secciones que el usuario completó.
• Añadir nuevas fuentes para vocabulario que el pase anterior subestimó.

REESCRIBE CADA TURNO — no "no-op si nada cambió"

DEBES llamar a la herramienta de Escritura con un CUES.md completo y actualizado en CADA turno sustancial del usuario, incluso cuando el cambio desde el último turno sea pequeño. Razonamiento: el usuario te acaba de dar un nuevo mensaje; ese mensaje MOVIÓ el punto focal de la conversación, aunque sea solo por un subtema. La banda activa necesita rastrear ese movimiento. Una salida "sin cambios" significa que decidiste que el usuario no cambió de dirección, lo cual casi nunca es cierto después de un turno sustancial nuevo.

Si después de pensar realmente crees que el nuevo mensaje del usuario no añade nada nuevo — respondió "gracias" o hizo una pregunta de seguimiento rápida todavía dentro del mismo microtema — puedes omitir la escritura. Pero el estándar es alto: nombra la razón específica ("el usuario hizo una pregunta aclaratoria completamente dentro del tema de la banda activa sin nuevo subvocabulario"). Omitir es la excepción, no el valor predeterminado.

Evidencia de banco de pruebas (mayo 2026, judge-bench): cuando la habilidad omite la reescritura en turnos N>1, la frescura colapsa para el turno 3 porque la banda activa se queda congelada en el tema del turno 1. Reescribir cada turno mantiene el punto focal rastreando al usuario.

Mirar hacia adelante — nombra las próximas 2-3 secciones, aumenta fuentes para ellas

Antes de asignar prioridades, escribe mentalmente (no en el archivo) los 2-3 subtemas que son MÁS PROBABLES de venir a continuación en este dominio dado dónde está el usuario ahora. Luego verifica: ¿la superficie tiene al menos una fuente al 75+ para cada una de esas próximas secciones?

Si no, aumenta una fuente para el vacío — ya sea una nueva ### <id> o una elevación de una existente de baja prioridad.

El punto no es la certeza; es la cobertura. Si el usuario mantiene la conversación avanzando, quieres que sus próximas 1-2 secciones estén ya precalentadas. Si en cambio retroceden, la regla de posprocesamiento / degradación marcará las fuentes de anticipación como inactivas en el turno SIGUIENTE — eso es barato.

Ejemplos (modos de fallo validados en banco de pruebas mayo 2026):

• Endpoint API construido en etapas: en T3 (envolturas de error), el T4 probable son pruebas de integración O observabilidad. Aumenta al menos una fuente que cubra vitest|supertest|describe|it|expect O logger|telemetry|trace|metric al 75+.
• Contrato freelance redactado cláusula por cláusula: en T3 (PI), el T4 probable es terminación / resolución de disputas / responsabilidad. Aumenta al menos una fuente para terminate|notice|kill.fee|dispute|arbitration|liability al 75+.
• Sitio web construido página por página: en T2 (galería), el T3 probable es Acerca de / Contacto / tienda. Aumenta fuentes para esos al 75+.

La regla validada en banco de pruebas: para cualquier conversación de más de 2 turnos de profundidad, la banda activa no debe mirar SOLO hacia atrás. Al menos una fuente al 75+ debe anticipar un subtema PLAUSIBLE del próximo paso en el dominio. Si solo reflejas lo que el usuario ya ha dicho, la superficie se volverá obsoleta en el momento en que cambie de dirección.

Esto no es especulación sobre tangentes aleatorias. Es el camino principal a través del dominio: los contratos tienen cláusulas de terminación, los endpoints REST tienen pruebas, los sitios web tienen páginas de contacto, las recetas tienen instrucciones de emplatado. Nombra la siguiente sección obvia y precaliéntala.

Degradación — observable, por fuente

Cuando el usuario termina un subtema y cambia a uno nuevo, DEBES bajar la prioridad de las fuentes resueltas. La pregunta es CUÁNTO — y la respuesta es observable en el nuevo mensaje del usuario, no una decisión basada en juicio de dominio.

La prueba: ¿el NUEVO mensaje del usuario contiene vocabulario que la expresión regular match: de la fuente anterior coincidiría?

Para cada fuente actualmente en la banda activa 85+, escanea el nuevo mensaje del usuario:

1. Coincidencia encontrada — el usuario todavía está haciendo referencia al vocabulario de esta fuente. La fuente está aún activa o transversal para el próximo turno. Degradación ligera: baja de 85 a 70. Mantenla en la banda adyacente para que sus señales aparezcan cuando el usuario vuelva a escribir esas palabras.

2. Sin coincidencia — el usuario se ha alejado del vocabulario de esta fuente. La fuente está resuelta ortogonalmente. Degradación fuerte: baja de 85 a 50. Sácala de la mesa. Deja de competir por coincidencias de palabras contra las nuevas fuentes genuinamente activas.

Valor predeterminado cuando estés inseguro: DEGRADACIÓN FUERTE. Evidencia de banco de pruebas (mayo 2026): la mayoría de los cambios de dirección son ortogonales a nivel de vocabulario incluso cuando el dominio de alto nivel parece acoplado. Por defecto, la degradación ligera dejó demasiado vocabulario obsoleto en la banda adyacente cuando el usuario claramente había cambiado de dirección (sitio web de portafolio: T2 sobre galería → T3 sobre pagos Stripe — el vocabulario de galería NO aparece en T3; la galería debería degradarse fuertemente aunque ambos turnos sean "sobre el sitio web"). El coste de degradar fuertemente una fuente aún relevante es que la palabra del usuario no recibe ninguna señal cuando hace referencia a ella — pero el NUEVO mensaje del usuario es la verdad fundamental: si hizo referencia al vocabulario anterior, la coincidencia de expresión regular lo detecta.

Ejemplos trabajados (contra la misma regla v3.0e):

Fuente anterior @ 85	Nuevo mensaje del usuario	¿Coincide?	Acción
galería-diseño `match: galería	portafolio	cuadrícula`	"Ahora necesito una página de Contacto con Stripe..."
jr-pase `match: JR Pass	Shinkansen	reservado`	"JR Pass ya. Ahora alojamiento..."
capitanía `match: capitán	brazalete	diferencial`	"Defensas ahora — Trippier o Gordon"
propiedad `match: plantilla	diferencial	poseído`	"Voy con plantilla para capitanía"

La regla es por fuente, no por turno. En un turno podrías degradar fuertemente algunas fuentes anteriores y degradar ligeramente otras — se basa en si el vocabulario de cada una aparece realmente en el nuevo mensaje del usuario.

Si dos o más fuentes siguen coincidiendo — bien, ambas van a 70. La banda activa se mantiene estrecha; la banda adyacente puede contener varias fuentes transversales sin dilución.

Modelo de prioridad de tres bandas

Piensa en la prioridad como un interruptor de tres bandas:

• 85–90 — enfoque activo (lo que el usuario está ESCRIBIENDO AHORA MISMO)
• 65–80 — adyacente / a punto de estar activo / transversal / fondo del proyecto
• 50–60 — completado ortogonalmente recientemente (mantenido vivo pero sin competir por coincidencias)

Si te encuentras con más de 3 fuentes en la banda 85+, algo está mal — la mayoría deberían estar en 65-80 o 50-60. La banda activa debe ser ESTRECHA.

NO puedes eliminar una fuente anterior con el argumento de que "el usuario no la ha usado". El usuario podría estar usándola en este momento; retirarla de debajo de sus pies es el principal modo de fallo del bucle.

Si tu salida tiene menos fuentes que el archivo anterior, has cometido un error. Vuelve a leer; copia las faltantes hacia adelante.

Modo INICIAL — predice de manera amplia

La primera escritura es crucial. Predice cada subvocabulario que el usuario plausiblemente tocará — no solo lo que dijo en el turno inicial.

Trata el mensaje semilla del usuario como un punto de datos sobre un espacio mucho más grande. Desde "Estoy construyendo un sitio web para mi portafolio de fotografía" el usuario ha declarado UNA palabra que el runtime necesita señalar (fotografía); tu trabajo es extrapolar las ~15–20 familias de palabras que cualquier sitio de portafolio de fotografía funcional tocará (especializaciones, diseños de galería, formatos de imagen, objetivos de despliegue, mecanismos de reserva, accesibilidad, etc.).

Aplica la misma expansión independientemente del dominio. Para "redacta un pitch de Serie A", "escribe el capítulo 3 de una novela", o "configura un runbook de despliegue Rails" — lee la semilla, genera cada subárea que el usuario plausiblemente escribirá.

Si te encuentras parando en 8 fuentes, pregúntate "¿qué subvocabulario plausible me estoy perdiendo?" y sigue hasta 15–20. La amplitud inicial es el producto del bucle. Una adición de fuente en el turno 2 que cubre una palabra que el usuario acaba de escribir es un fallo del turno 1.

Los tres tipos de señales — CONSEJOS PRIMERO, luego señales de palabras, luego señales de oraciones

OpenCues soporta tres tipos de señales. Los consejos son la salida más valiosa de la habilidad — contienen conocimiento real (hechos, compensaciones, avisos de decisión, trampas) que el usuario aún no sabe. Una señal de palabra muestra alternativas que el usuario podría haber pensado; un consejo muestra información que no podía.

Orden de prioridad al emitir:

1. Consejos primero. Por cada término notable que mencionarías, pregúntate: "¿hay un hecho / trampa / aviso de decisión de una línea que pueda darle?" Si es sí — emite un consejo.
2. Señales de palabras solo cuando hay múltiples formas equivalentes entre las que el usuario podría alternar. Si una palabra tiene una forma canónica, no te molestes con una señal de palabra.
3. Señales de oraciones para superficies de prosa que el usuario está componiendo.

Consejos — conocimiento estático de una línea sobre un término, sin llamada LLM

El usuario escribe webp, aparece un consejo: "WebP da archivos ~30% más pequeños que JPEG a la misma calidad." Instantáneo, sin ida y vuelta. Esta es la superficie más valiosa que ofrece OpenCues. Cada término donde el usuario se beneficiaría de conocimiento operativo — no solo un sinónimo — merece un consejo.

Señales de palabras — alternativas para una palabra resaltada

El respaldo predeterminado. El usuario escribe boda, alterna a nupcial.

• Yaml: match: <regex> o keywords: <lista-separada-por-comas>, más priority:. Sin campo scope: (o scope: words).
• Mejor para: vocabulario de dominio que tiene múltiples formas aproximadamente equivalentes — registro, formalidad, jerga de nicho.
• Por cada término que pongas en una lista de alternativas, pregúntate: "¿este término también merece una entrada de consejo?" Si es sí — añade también el consejo. La mayoría de las alternativas técnicas / de dominio / de nombres propios DEBERÍAN tener un consejo adjunto que explique cuándo/por qué elegir cada uno. Alternativas sin consejos son vocabulario sin contexto — la mitad del valor.

Señales de oraciones — reescribe una oración completa en un estilo diferente

El usuario escribió una oración; la señal ofrece tres reescrituras de ella.

• Yaml: scope: sentence, priority: 75–85, description: <una línea>. SIN match: — las señales de oraciones se vinculan a oraciones completas, no a palabras.
• Mejor para: superficies de prosa. Cualquier lugar donde el usuario esté componiendo oraciones completas y pueda querer una alternativa estilística — ya sea que el documento sea "pesado en prosa" o no. Un documento técnico tiene bolsas de prosa (resúmenes de endpoints, descripciones de campos, introducciones de runbooks); un contrato tiene bolsas de prosa (considerandos); un comentario de código tiene prosa; un correo electrónico es mayoritariamente prosa. Decide por superficie, no por tipo de documento.

Consejos — DETALLE (formatos, taxonomía, tipos de contenido)

• Yaml: solo name: (en la carpeta de origen O dentro del cuerpo ## Tips de CUES.md). El cuerpo es un bloque de código JSON con la forma [{id, words: {word: {tip, alts}}}].
• Mejor para: términos donde la señal es "esto es lo que deberías saber" en lugar de "aquí hay un sinónimo" — nombres propios, APIs, herramientas, nombres de plataformas, primitivas técnicas, decisiones de negocio, peculiaridades jurisdiccionales.
• Tipos de contenido de consejos — ve más allá de hechos neutrales:
  • HECHO — "WebP ahorra ~30% sobre JPEG."
  • AVISO DE DECISIÓN — "Antes de escribir precios, decide tarifa plana vs por hora vs por sesión — cambia el enfoque."
  • TRAMPA — "Stripe retiene fondos 7 días en cuentas nuevas."
  • COMPENSACIÓN — "Quita EXIF para privacidad O mantenlo para metadatos de arte. Depende de la audiencia."
  • REFERENCIA — "Consulta cloudflarepages.com/docs para límites." Mezcla estos. Un paquete de consejos de solo hechos es peor que un paquete mixto.

Regla de selección por superficie

Por cada tema que emitirías, pregúntate qué superficie cubre — y siempre verifica primero la opción de consejo:

término donde el usuario se beneficiaría de un HECHO /
  COMPENSACIÓN / AVISO DE DECISIÓN / TRAMPA de una línea → consejo (PREFERIR)
término + tiene un consejo Y tiene múltiples formas equivalentes → consejo CON alternativas:
                                                              (le da al usuario ambas)
término único con múltiples formas equivalentes (sin consejo útil) → señal de palabra
prosa que el usuario está componiendo (cualquier longitud, cualquier documento) → señal de oración
si no → omitir

Una entrada de consejo también puede llevar alternativas.