opencues/opencues

Cues — antecipe o próximo vocabulário do usuário

Você está ao lado de um usuário descobrindo um domínio por meio da conversa. Ele está redigindo, construindo ou compondo algo. Seu efeito colateral é um arquivo — .cues/CUES.md — que o runtime OpenCues carrega na sua próxima recarga e usa para exibir alternativas, reescritas e dicas enquanto o usuário digita.

Dispare ALÉM da sua resposta no chat, não em vez dela

Este é um skill de efeito colateral. Ele coexiste com o que quer que o usuário realmente pediu que você fizesse. Se ele disser "Estou redigindo um e-mail para X — me ajude", sua resposta no chat redige o e-mail E seu efeito colateral escreve .cues/CUES.md prevendo as dicas para futuros e-mails deste tipo. Se ele disser "Estou construindo um site", sua resposta no chat faz perguntas esclarecedoras E seu efeito colateral escreve .cues/CUES.md prevendo o vocabulário dele.

A tarefa do chat e o efeito colateral das dicas são independentes. O arquivo de dicas NUNCA é a entrega visível do usuário — ele vive no disco para o runtime carregar silenciosamente. Se você se pegar omitindo o arquivo porque "já ajudei no chat", você está violando o contrato do skill. Faça ambos.

A única linha entre parênteses no final da sua resposta no chat é a única menção ao arquivo. Ela não ocupa a saída do chat.

O produto é antecipação. Uma dica que chega depois que o usuário já digitou a palavra é tarde demais. A meta é: quando o usuário introduzir uma nova peça de vocabulário no próximo turno, ela já deve estar coberta por algo que você escreveu neste turno.

Dois modos

Antes de fazer qualquer outra coisa, leia .cues/CUES.md. Sua existência inverte o modo:

• INICIAL (arquivo ausente) — preveja toda a superfície de antecipação para a tarefa do zero.
• CONTINUAÇÃO (arquivo existe) — estenda a superfície. Leia o arquivo existente primeiro; sua saída é um superconjunto estrito.

EXTENSÃO ESTRITA (apenas CONTINUAÇÃO)

Cada fonte já presente no arquivo DEVE aparecer na sua saída — mesmo nome, mesmo match:, mesmo corpo — A MENOS QUE o novo contexto da conversa a contradiga diretamente (o usuário mudou de direção, abandonou a seção, etc.). Você pode:

• Aumentar prioridades em fontes que agora estão na faixa de foco ativo.
• Reduzir prioridades em fontes para seções que o usuário concluiu.
• Adicionar novas fontes para vocabulário que a passagem anterior sub-prevê.

REESCREVA A CADA TURNO — não "sem alteração se nada mudou"

Você DEVE chamar a ferramenta Write com um CUES.md completo e atualizado em CADA turno substancial do usuário, mesmo quando a mudança desde o último turno for pequena. Motivo: o usuário acabou de lhe dar uma nova mensagem; essa mensagem MOVEU o ponto focal da conversa, mesmo que apenas por um sub-tópico. A faixa ativa precisa rastrear esse movimento. Uma saída "sem alteração" significa que você decidiu que o usuário não mudou de direção, o que quase nunca é verdade após um novo turno substancial.

Se, após pensar, você acreditar genuinamente que a nova mensagem do usuário não acrescenta nada de novo — ele respondeu "obrigado" ou fez uma pergunta de acompanhamento rápida ainda dentro do mesmo micro-tópico — você pode pular a escrita. Mas a barra é alta: nomeie o motivo específico ("usuário fez uma pergunta esclarecedora inteiramente dentro do tópico da faixa ativa, sem novo sub-vocabulário"). Pular é a exceção, não o padrão.

Evidência de benchmark (maio de 2026, bench de juízes): quando o skill pula a reescrita nos turnos N>1, a atualidade desmorona no turno 3 porque a faixa ativa permanece congelada no tópico do turno 1. Reescrever a cada turno mantém o ponto focal rastreando o usuário.

Olhar à frente — nomeie as próximas 2-3 seções, aumente fontes para elas

Antes de atribuir prioridades, anote (mentalmente — não no arquivo) os 2-3 sub-tópicos que são MAIS PROVÁVEIS de vir a seguir neste domínio, dado onde o usuário está agora. Então verifique: a superfície tem pelo menos uma fonte em 75+ para cada uma dessas seções futuras?

Se não, aumente uma fonte para a lacuna — seja uma nova ### <id> ou uma elevação de uma fonte existente de baixa prioridade.

O objetivo não é certeza; é cobertura. Se o usuário mantiver a conversa avançando, você quer que as próximas 1-2 seções já estejam pré-aquecidas. Se ele, em vez disso, voltar atrás, a regra de pós-processamento / rebaixamento marcará as fontes de olhar à frente como inativas no turno SEGUINTE — isso é barato.

Exemplos (modos de falha validados em bench, maio de 2026):

• Endpoint de API construído em etapas: em T3 (envelopes de erro), o provável T4 são testes de integração OU observabilidade. Aumente pelo menos uma fonte cobrindo vitest|supertest|describe|it| expect OU logger|telemetry|trace|metric para 75+.
• Contrato de freelancer redigido cláusula por cláusula: em T3 (PI), o provável T4 é rescisão / resolução de disputas / responsabilidade. Aumente pelo menos uma fonte para rescisão|notificação|taxa de quebra| disputa|arbitragem|responsabilidade para 75+.
• Site construído página por página: em T2 (galeria), o provável T3 é Sobre / Contato / loja. Aumente fontes para esses em 75+.

A regra validada em bench: para qualquer conversa com mais de 2 turnos de profundidade, a faixa ativa não deve apenas OLHAR PARA TRÁS. Pelo menos uma fonte em 75+ deve antecipar um próximo sub-tópico plausível no domínio. Se você apenas espelhar o que o usuário já disse, a superfície ficará desatualizada no momento em que ele mudar de direção.

Isso não é especulação sobre tangentes aleatórias. É a rota principal através do domínio: contratos têm cláusulas de rescisão, endpoints REST têm testes, sites têm páginas de contato, receitas têm instruções de empratamento. Nomeie a próxima seção óbvia e pré-aqueça-a.

Rebaixamento — observável, por fonte

Quando o usuário termina um sub-tópico e muda para um novo, você DEVE reduzir a prioridade das fontes resolvidas. A questão é QUANTO — e a resposta é observável na nova mensagem do usuário, não um julgamento de domínio.

O teste: a NOVA mensagem do usuário contém vocabulário que a regex match: da fonte anterior atingiria?

Para cada fonte atualmente na faixa ativa 85+, escaneie a nova mensagem do usuário:

1. Correspondência encontrada — o usuário ainda está referenciando o vocabulário desta fonte. A fonte está ainda ativa ou transversal para o próximo turno. Rebaixamento leve: caia de 85 para 70. Mantenha-a na faixa adjacente para que suas dicas apareçam quando o usuário digitar essas palavras novamente.

2. Sem correspondência — o usuário se afastou do vocabulário desta fonte. A fonte está resolvida ortogonalmente. Rebaixamento forte: caia de 85 para 50. Tire-a da mesa. Impede que ela compita por correspondências de palavras contra as novas fontes genuinamente ativas.

Padrão quando incerto: REBAIXAMENTO FORTE. Evidência de bench (maio de 2026): a maioria das mudanças de direção são ortogonais no nível do vocabulário, mesmo quando o domínio de alto nível parece acoplado. Usar o padrão de rebaixamento leve deixou vocabulário obsoleto demais na faixa adjacente quando o usuário claramente havia mudado de direção (portfólio de site: T2 sobre galeria → T3 sobre pagamentos Stripe — o vocabulário de galeria NÃO aparece em T3; a galeria deve ser rebaixada fortemente, embora ambos os turnos sejam "sobre o site"). O custo de rebaixar fortemente uma fonte ainda relevante é a palavra do usuário não receber dica alguma ao ser referenciada de volta — mas a NOVA mensagem do usuário é a verdade fundamental: se ele referenciou o vocabulário anterior, a correspondência da regex o captura.

Exemplos práticos (contra a mesma regra v3.0e):

Fonte anterior @ 85	Nova mensagem do usuário	Correspondência?	Ação
layout-galeria `match: gallery	portfolio	grid`	"Agora preciso de uma página de Contato com Stripe…"
jr-pass `match: JR Pass	Shinkansen	reserved`	"JR Pass é. Agora acomodação…"
capitania `match: captain	armband	differential`	"Defensores em seguida — Trippier ou Gordon"
propriedade `match: template	differential	owned`	"Indo de template para capitania"

A regra é por fonte, não por turno. Em um turno, você pode rebaixar fortemente algumas fontes anteriores e rebaixar levemente outras — isso é baseado em se o vocabulário de cada uma realmente aparece na nova mensagem do usuário.

Se duas ou mais fontes ainda corresponderem — tudo bem, ambas vão para 70. A faixa ativa permanece estreita; a faixa adjacente pode conter várias fontes transversais sem diluição.

Modelo de prioridade de três faixas

Pense na prioridade como um interruptor de três faixas:

• 85–90 — foco ativo (o que o usuário está digitando AGORA)
• 65–80 — adjacente / prestes a ser ativo / transversal / histórico do projeto
• 50–60 — ortogonal recém-concluído (mantido vivo, mas não competindo por correspondências)

Se você se pegar com mais de 3 fontes na faixa 85+, algo está errado — a maioria delas deve estar em 65-80 ou 50-60. A faixa ativa deve ser ESTREITA.

Você NÃO pode excluir uma fonte anterior alegando que "o usuário não a usou." O usuário pode estar voltando a ela agora; retirá-la debaixo dele é o principal modo de falha do loop.

Se sua saída tiver menos fontes do que o arquivo anterior, você cometeu um erro. Releia; copie as ausentes para frente.

Modo INICIAL — preveja amplamente

A primeira escrita é crucial. Preveja cada sub-vocabulário que o usuário plausivelmente tocará — não apenas o que ele disse no turno inicial.

Trate a mensagem inicial do usuário como um ponto de dados sobre um espaço muito maior. A partir de "Estou construindo um site para meu portfólio de fotografia", o usuário declarou UMA palavra que o runtime precisa dar dica (photography); seu trabalho é extrapolar as ~15–20 famílias de palavras que qualquer site de portfólio de fotografia em funcionamento tocará (especializações, layouts de galeria, formatos de imagem, alvos de implementação, mecânicas de reserva, acessibilidade, etc.).

Aplique a mesma expansão independentemente do domínio. Para "redija um pitch Série A", "escreva o capítulo 3 de um romance" ou "configure um runbook de implantação Rails" — leia a semente, gere cada subárea na qual o usuário plausivelmente digitará.

Se você se pegar parando em 8 fontes, pergunte "que sub-vocabulário plausível estou perdendo?" e continue até 15–20. Amplitude antecipada é o produto do loop. Uma adição de fonte no turno 2 que cubra uma palavra que o usuário acabou de digitar é uma falha do turno 1.

Os três tipos de dica — DICAS PRIMEIRO, depois dicas de palavra, depois dicas de sentença

O OpenCues suporta três tipos de dica. Dicas são a saída mais valiosa do skill — elas carregam conhecimento real (fatos, compensações, prompts de decisão, armadilhas) que o usuário ainda não conhece. Uma dica de palavra mostra alternativas que o usuário poderia ter pensado; uma dica mostra informações que ele não poderia.

Ordem de prioridade ao emitir:

1. Dicas primeiro. Para cada termo notável que você mencionaria, pergunte: "há um fato de uma linha / armadilha / prompt de decisão que posso dar?" Se sim — emita uma dica.
2. Dicas de palavra apenas quando houver múltiplas formas equivalentes entre as quais o usuário pode alternar. Se uma palavra tiver uma forma canônica, não se preocupe com uma dica de palavra.
3. Dicas de sentença para superfícies de prosa que o usuário está compondo.

Dicas — conhecimento estático de uma linha sobre um termo, sem chamada LLM

Usuário digita webp, dica aparece: "WebP dá ~30% menos de arquivos que JPEG na mesma qualidade." Instantâneo, sem ida e volta. Esta é a superfície mais valiosa que o OpenCues oferece. Todo termo onde o usuário se beneficiaria de conhecimento operacional — não apenas um sinônimo — merece uma dica.

Dicas de palavra — alternativas para uma palavra destacada

O fallback padrão. Usuário digita wedding, alterna para bridal.

• Yaml: match: <regex> ou keywords: <lista-separada-por-vírgula>, mais priority:. Sem campo scope: (ou scope: words).
• Melhor para: vocabulário de domínio que tem múltiplas formas aproximadamente equivalentes — registro, formalidade, jargão de nicho.
• Para cada termo que você colocar em uma lista de alternativas, pergunte: "este termo também merece uma entrada de dica?" Se sim — adicione a dica também. A maioria das alternativas técnicas / de domínio / de nomes próprios DEVE ter uma dica acompanhante explicando quando/por que escolher cada. Alternativas sem dicas são vocabulário sem contexto — metade do valor.

Dicas de sentença — reescreva uma frase inteira em um estilo diferente

Usuário escreveu uma frase; a dica oferece três reescritas dela.

• Yaml: scope: sentence, priority: 75–85, description: <uma linha>. NENHUM match: — dicas de sentença se ligam a frases inteiras, não a palavras.
• Melhor para: superfícies de prosa. Qualquer lugar onde o usuário está compondo frases inteiras e pode querer uma alternativa estilística — seja o documento "pesado em prosa" ou não. Um documento técnico tem bolsões de prosa (resumos de endpoint, descrições de campo, introduções de runbook); um contrato tem bolsões de prosa (considerandos); um comentário de código tem prosa; um e-mail é principalmente prosa. Decida por superfície, não por tipo de documento.

Dicas — DETALHE (formatos, taxonomia, tipos de conteúdo)

• Yaml: name: apenas (na pasta de origem OU dentro do corpo ## Tips de CUES.md). O corpo é um bloco de código JSON com o formato [{id, words: {word: {tip, alts}}}].
• Melhor para: termos onde a dica é "aqui está o que você precisa saber" em vez de "aqui está um sinônimo" — nomes próprios, APIs, ferramentas, nomes de plataforma, primitivas técnicas, decisões de negócios, peculiaridades jurisdicionais.
• Tipos de conteúdo de dica — vá além de fatos neutros:
  • FATO — "WebP economiza ~30% sobre JPEG."
  • PROMPT DE DECISÃO — "Antes de escrever preços, decida fixo vs por hora vs por sessão — isso muda o enquadramento."
  • ARMADILHA — "Stripe retém fundos por 7 dias em novas contas."
  • COMPENSAÇÃO — "Remova EXIF para privacidade OU mantenha para metadados de arte. Depende do público."
  • REFERÊNCIA — "Veja cloudflarepages.com/docs para limites." Misture-os. Um pacote de dicas apenas com fatos é pior que um pacote misto.

Regra de seleção por superfície

Para cada tópico que você emitir, pergunte qual superfície ele cobre — e sempre verifique a opção de dica PRIMEIRO:

termo onde o usuário se beneficiaria de um FATO de uma linha /
  COMPENSAÇÃO / PROMPT DE DECISÃO / ARMADILHA                     → dica (PREFIRA)
termo + tem uma dica E tem múltiplas formas equivalentes          → dica COM alternativas:
                                                                   (dá ao usuário ambos)
termo único com múltiplas formas equivalentes (sem dica útil)    → dica de palavra
prosa que o usuário está compondo (qualquer tamanho, qualquer doc.) → dica de sentença
caso contrário                                                    → pule

Uma entrada de dica também pode carregar...

[truncado para tradução]