ll-skills 1.0.0

package/skills/ll-desarmar/referencias/execucao-adversarial.md

@@ -0,0 +1,217 @@
+# Execução adversarial, relatório e auditoria
+
+Lido por quem orquestra antes de despachar (D2) e por **todo executor e todo auditor** como
+referência de método. Traz: a disciplina de execução, as receitas por tipo de incógnita, o
+esqueleto obrigatório do relatório e o protocolo de auditoria de contexto limpo.
+
+---
+
+## A disciplina: reprova primeiro
+
+O teste não existe para mostrar que o sistema funciona. Existe para descobrir **onde ele
+para de funcionar**, enquanto isso ainda é barato. Três consequências operacionais:
+
+- **Procure o resultado que reprova.** Depois do primeiro número bom, a tarefa não acabou:
+  ela vira "qual entrada faz este número desabar?". Quem executa é o adversário do próprio
+  sistema durante a execução inteira.
+- **Desconfie da folga.** Aceite de 95% batido com 99,8% costuma significar uma de três
+  coisas: a amostra é fácil, a métrica é proxy do que importa, ou o ground truth veio do
+  próprio sistema. Teste as três hipóteses antes de comemorar.
+- **Aprovação falsa é pior que não testar.** Não testar deixa a incerteza visível; aprovar
+  errado compra confiança que será transferida para camadas que ninguém olhou.
+
+### Amostra adversarial
+
+Monte por **composição declarada**, não por sorteio. Uma amostra de 30 bem escolhida vence
+uma de 500 aleatória, porque o que decide é a cobertura de classes de entrada, não o n:
+
+- os formatos e origens **distintos** (fornecedores, layouts, dialetos, versões de API);
+- o caso que já deu problema uma vez em contexto de baixo risco — o presságio;
+- o caso com histórico sujo (retificação, correção posterior, dado migrado, duplicata);
+- o caso fora do perfil-alvo (usuário atípico, volume extremo, campo vazio, acento, unidade
+  diferente);
+- a cauda que o desenho assume ser rara — meça se ela é mesmo.
+
+Registre no relatório a composição real e **toda substituição**: "previstos 3 fornecedores,
+o terceiro não tinha dado público na janela; substituído por X, que compartilha o layout de
+duas colunas — a propriedade que interessava".
+
+### Ground truth independente
+
+Em ordem de força: fonte oficial externa conferida à mão > dois revisores independentes com
+adjudicação do desacordo > critério preditivo externo (o instrumento acerta o que aconteceu
+depois?) > caminho duplo independente com juiz nos desacordos. Medir a saída do sistema
+contra outra saída do mesmo sistema não é ground truth — é consistência interna, e ela é
+alta justamente quando o erro é sistemático.
+
+Quando o ground truth exige conferência manual, declare **quantos itens foram conferidos
+visualmente** — é esse número, não o n total, que sustenta a afirmação de erro zero.
+
+### Quebra por classe de entrada
+
+O agregado é a média de coisas diferentes e mente por construção. Toda métrica sai em tabela
+por classe: por fonte, por formato, por faixa de tamanho, por tier de modelo, por período.
+É dessa tabela que sai a **fronteira de validade** — "0% de erro neste formato; layouts de
+duas colunas têm 35–100% de erro e ficam fora do MVP" é um resultado útil; "erro médio de
+6%" não decide nada.
+
+### Regras de execução que mudam o número
+
+- **Determinístico fica em script.** Hash, dedupe, contagem, replay, diff, junção: código.
+  Julgamento de modelo só onde há ambiguidade real — e ali, com o resultado auditável.
+- **Meça com o tier que o produto vai usar.** Tier melhor infla qualidade; tier pior infla
+  custo. Num caso real, o modelo mínimo errou classificações com confiança máxima e derrubou
+  o recall do sinal central de 100% para 7,7% — o tier é parte do desenho, não detalhe de
+  execução.
+- **Economia unitária mede o custo variável de UMA unidade ativa**, com preços reais de
+  tabela, no tier que passou nos testes de qualidade, e por um mês simulado — incluindo o
+  mês de onboarding como pior caso. Custo apurado sob assinatura, crédito ou ambiente
+  subsidiado responde outra pergunta.
+- **Proveniência na medição.** Cada resultado carrega de onde veio (script, versão, lote,
+  modelo). É o que permite purgar cirurgicamente e re-medir quando um defeito aparece.
+
+### Correção estrutural é achado de primeira classe
+
+Testes desenhados para falsear premissas encontram defeitos que nenhuma revisão de código
+encontra: chaves naturais que não existem no mundo real, identidades que colidem entre
+contextos, idempotência quebrada por um campo volátil, heurística que classifica pelo nome
+do arquivo. Numa POC real, as **12 correções estruturais** foram o produto principal — mais
+valiosas que os 6 critérios aprovados.
+
+Para cada uma registre: o defeito com o dado real que o expôs, a correção aplicada, o
+re-teste, e a **recomendação para o sistema real**. Se a correção mudou o resultado do
+aceite, o relatório mostra os dois números, antes e depois.
+
+---
+
+## Receitas por tipo de incógnita
+
+| Incógnita | O que rodar | O que registrar |
+|---|---|---|
+| Fidelidade de extração/transformação | amostra adversarial + ground truth manual, item a item | taxa de erro **por classe de entrada** e por campo; quantos itens conferidos visualmente |
+| Concordância semântica / classificação | dois caminhos independentes + adjudicação dos desacordos | concordância bruta **e** acurácia adjudicada; a natureza dos desacordos (muitos são defeito do rótulo, não do classificador) |
+| Poder estatístico / convergência | simulação com verdade conhecida sob o tráfego realmente projetado | curva por volume; qual alavanca move o resultado e qual não move |
+| Economia unitária | bottom-up com preços reais, um mês de uma unidade ativa | típico e pior caso; % do menor preço da tese |
+| Regime contínuo | cron/timer por N dias sem intervenção, dashboard de 3–5 métricas | intervenções manuais não planejadas (o aceite é a **ausência** delas); fila humana por dia; o que o dia 1 quebrou |
+| Dependência externa/legal | memorando de perguntas objetivas + segunda opinião adversarial | risco classificado, mitigação escrita e o **requisito de arquitetura** que decorre |
+| Percepção humana / desejabilidade | ver `humanos-e-substitutos.md` | componente objetivo **e** subjetivo, separados |
+
+---
+
+## §Relatório — esqueleto obrigatório
+
+Grave em `docs/desarmar/resultados/<slug>.md`:
+
+<esqueleto-relatorio>
+# Teste {N} — {título} — Resultados
+
+> Executado em {datas}, sobre {dados reais / simulação}. Reprodutível em `{caminho}`.
+> Premissa sob teste: "{afirmação falsificável}".
+> Aceite pré-registrado em {data de congelamento}: {texto literal do plano}.
+> Reprova se: {texto literal do plano}.
+
+## O que rodou
+Amostra real (n e composição, com as substituições e o porquê) · ground truth e como foi
+estabelecido · comandos, scripts e caminhos · modelo/tier e versão · período.
+
+## Dados medidos
+Tabela agregada + **tabela por classe de entrada**. Números crus antes de qualquer
+interpretação.
+
+## Aceite, critério a critério
+| Critério pré-registrado | Medido | Passou? |
+|---|---|---|
+| {texto literal} | {número} | ✅ / ⚠️ no fio / ❌ |
+
+## Fronteira de validade
+Onde vale, com número. Onde **não** vale, com número. Que condição precisa ser verdadeira
+para o resultado se sustentar em produção.
+
+## Achados colaterais e correções estruturais
+Defeito → dado real que o expôs → correção → re-teste → recomendação para o sistema real.
+
+## Custo e prazo
+Orçado {X} × real {Y}, por etapa. Tokens, chamadas, horas de conferência manual.
+
+## O que este teste NÃO prova
+Explícito. Camadas não tocadas, regimes não exercitados, populações não representadas.
+
+## Veredicto proposto
+{um dos cinco do vocabulário fechado} — uma frase de justificativa com o número que decide.
+</esqueleto-relatorio>
+
+---
+
+## §Auditoria — contexto limpo sobre o que passou
+
+Todo critério **aprovado** é auditado por um agente que não viu a execução. A auditoria roda
+em Opus, em subagente novo, e é onde a rodada mais se paga: num caso real ela reprovou um
+critério que os números agregados davam por aprovado (recall real de 7,7%), desfez uma
+conclusão de "omissão confirmada" que era artefato da fonte, e validou o modelo de dados com
+varredura completa.
+
+<brief-modelo-auditor>
+Você audita, de forma adversarial, um critério de aceite que foi dado como aprovado em
+{PROJETO}. Sua tarefa é reprová-lo se ele for reprovável.
+
+CONTEXTO E MOTIVAÇÃO
+Este critério vai autorizar {decisão que ele destrava}. Aprovações falsas são o modo de
+falha mais caro deste processo, porque a confiança conquistada aqui será transferida para
+camadas que ninguém mediu. Encontrar um problema agora vale mais do que confirmar o
+resultado. Você não viu — e não deve procurar — o raciocínio de quem executou.
+
+DADOS
+1. {abs}/docs/desarmar/plano-de-testes.md §{teste} — o aceite pré-registrado, literal.
+2. {abs}/docs/desarmar/resultados/{slug}.md — o relatório, seções "O que rodou" e "Dados
+   medidos".
+3. {caminhos dos dados brutos, saídas do sistema e ground truth}
+
+INSTRUÇÕES
+Refaça a medição pelo caminho mais independente que os dados permitirem. Ataque nesta ordem:
+a métrica mede o que o critério afirma, ou mede um proxy que passa mais fácil? O denominador
+está certo — o que ficou fora da conta? A amostra cobre as classes que o plano prometeu? O
+ground truth é mesmo independente do sistema? O agregado esconde uma classe com desempenho
+inaceitável? Existe um caso plausível, dentro do escopo declarado, que o sistema erra?
+Construa esse caso e rode.
+Cobertura completa com rótulo de confiança por achado — alta, média ou baixa. Não filtre por
+severidade; filtrar é trabalho de quem consolida.
+
+CONTRATO DE SAÍDA
+Devolva em ≤ 400 palavras: **MANTÉM** ou **REPROVA** o critério; para cada achado, o número
+que o sustenta e o caminho do dado; e a métrica recalculada pelo seu caminho independente,
+lado a lado com a reportada. "Refiz por caminho independente e o número bate" é resultado
+válido e valioso — diga isso claramente quando for o caso.
+
+LIMITES
+Não edite o relatório nem nenhum arquivo do projeto. Não proponha redesenho de produto: seu
+escopo é a validade da medição.
+
+CRITÉRIOS DE SUCESSO
+Você recalculou pelo menos uma métrica por caminho independente; inspecionou manualmente ao
+menos {N} casos, incluindo os da classe de pior desempenho; e nomeou explicitamente a
+hipótese de amostra fácil, confirmando-a ou descartando-a com dado.
+</brief-modelo-auditor>
+
+Quando a auditoria reprova: rode o ciclo de correção, re-teste, e grave a **trajetória** no
+relatório — reprovou com X, corrigiu com Y, passou com Z. A trajetória é a lição
+transferível; só o número final não ensina nada.
+
+---
+
+## Anti-padrões de execução
+
+1. **Completar o aceite depois de ver os dados.** Se o plano estava incompleto, ele volta ao
+   portão de D0 antes de rodar — nunca depois.
+2. **Trocar a métrica no meio.** Métrica que muda durante a execução é métrica escolhida pelo
+   resultado.
+3. **Amostra da conveniência.** O que estava na pasta, o que a API devolve por padrão, os 10
+   primeiros. Composição declarada ou nada.
+4. **Erro médio como veredicto.** Sem quebra por classe não há fronteira de validade.
+5. **Ground truth contaminado.** Rótulo gerado pelo mesmo modelo, gabarito derivado da mesma
+   heurística, revisor que viu a saída do sistema antes de julgar.
+6. **Silenciar o desvio.** Toda diferença entre o plano e o que foi possível fazer vira nota
+   "Desvio do plano", com o efeito sobre a validade.
+7. **Construir o produto sob nome de POC.** Se o teste começa a exigir metade do sistema,
+   pare e reporte: o desenho está errado ou o premortem virou autorização para começar.
+8. **Descartar o código do teste sem colher as recomendações.** O código é descartável; as 12
+   correções que ele revelou, não.

package/skills/ll-desarmar/referencias/humanos-e-substitutos.md

@@ -0,0 +1,116 @@
+# Testes que exigem terceiros: kit, substituto e fronteira epistêmica
+
+Lido em D1, quando um teste depende de pessoas que não estão disponíveis agora — entrevista,
+avaliação cega, teste de percepção, parecer profissional. Nenhuma skill recruta humanos: o
+que ela faz é deixar o teste **pronto para disparar** e, se o humano decidir, rodar o
+substituto declarado com os limites do que ele prova escritos.
+
+---
+
+## Regra de ouro
+
+Persona simulada não é usuário. Advogado simulado não é parecer. A simulação é uma **ponte**
+que corrige o instrumento antes de gastar o recurso escasso — a atenção de gente real. Ela é
+legítima, e é desonesta apenas quando a fronteira do que prova fica implícita.
+
+O caso real que justifica a ponte: 10 personas com perfil de conhecimento oculto revelaram
+que **um acerto por chute em item verdadeiro/falso certificava domínio** — uma falha
+aritmética do instrumento, igualmente válida para humanos. A correção derrubou o
+falso-positivo de 34% para 12%. Nenhum humano precisou ser gasto para descobrir isso, e
+gente real teria sido gasta num instrumento defeituoso.
+
+---
+
+## O kit — monte sempre, mesmo quando o substituto vai rodar
+
+Grave em `docs/desarmar/kits/<slug>/`. É o que permite disparar o teste real no dia em que
+as pessoas existirem, sem re-derivar nada.
+
+| Peça | Conteúdo |
+|---|---|
+| `protocolo.md` | Quem recrutar (perfil, quantos, de onde, **fora do time**), roteiro minuto a minuto, o que o participante vê e não vê, ordem de apresentação e como ela é randomizada, tempo total, incentivo |
+| `instrumento/` | O material que o participante encontra: questionário, telas, tarefas, o produto do concorrente lado a lado, o que for |
+| `formulario.md` | Os itens de coleta, separados em **objetivos** (desempenho, tempo, taxa de detecção, escolha revelada) e **subjetivos** (n/10 concordam, escala, frase livre) |
+| `criterio.md` | O aceite pré-registrado, copiado literal do plano, com a data de congelamento e a decisão pré-comprometida nos dois ramos |
+| `analise.md` | Como os dados serão tabulados **antes** de existirem: qual tabela, qual corte, qual teste. Análise decidida depois dos dados escolhe o corte que confirma |
+
+### Cegueira, onde ela importa
+
+- Quem aplica não conhece a hipótese, ou aplica por roteiro fechado.
+- Quem avalia a saída não sabe qual condição a produziu.
+- Perguntas de desejabilidade medem **preferência revelada** sempre que possível: o que a
+  pessoa escolheu, pagou, abandonou ou copiou vale mais que o que ela declarou que faria.
+- Ordem randomizada entre participantes, para que a fadiga e a âncora não caiam sempre no
+  mesmo item.
+
+### Aceite de teste com humanos
+
+Sempre conjunto, com um componente objetivo e um subjetivo, e com n pequeno declarado —
+5 a 10 pessoas resolvem a maioria das perguntas de percepção. Modelo:
+*"delta ≥ 20 p.p. entre as condições **e** ≥ 7/10 participantes reconhecem o resultado como
+descrição justa do próprio desempenho"*.
+
+---
+
+## O substituto: simulação de personas
+
+Três salvaguardas, todas obrigatórias:
+
+1. **Perfil oculto do instrumento.** A persona recebe um perfil (o que sabe, o que não sabe,
+   como se comporta sob incerteza) e responde **em caráter**; quem avalia não vê o perfil.
+   Sem isso, a simulação mede o quanto o avaliador conhece o gabarito.
+2. **Diversidade declarada de perfis.** Cubra os regimes que o produto vai encontrar —
+   avançado, intermediário, iniciante, errático, adversarial —, com quantos de cada e por
+   quê. Personas todas cooperativas produzem um instrumento que só funciona com gente boazinha.
+3. **Fronteira epistêmica escrita no resultado**, no formato abaixo, dentro do próprio
+   relatório do teste.
+
+<fronteira-epistemica>
+## O que esta simulação prova e o que não prova
+
+**Prova** (propriedades aritméticas e estruturais do instrumento, válidas também para
+humanos): {ex. o escore certifica domínio a partir de uma única resposta correta em item
+binário; o gabarito desbalanceado alinha o chute ao acerto; a regra de corte deixa X% do
+mapa indeterminado}.
+
+**Não prova**: percepção subjetiva, aceitação, disposição a pagar, a estrutura real do
+conhecimento ou do comportamento humano, e qualquer efeito de contexto social. Nada aqui
+substitui {N} pessoas reais.
+
+**Estado**: instrumento corrigido em {caminho}, pronto para disparar. Item reclassificado de
+**bloqueio** para **validação pré-lançamento**, com dono {nome} e marco {quando}.
+</fronteira-epistemica>
+
+Rode as personas em **Opus** — julgamento em caráter com perfil oculto é exatamente o
+trabalho que degrada em modelo menor.
+
+## O substituto: segunda opinião adversarial em parecer profissional
+
+Para dependência legal, regulatória, contábil ou clínica: escreva primeiro o **memorando de
+perguntas objetivas** (numeradas, fechadas, cada uma com a decisão de produto que depende
+dela). Depois rode uma persona especialista da área **em modo adversarial**, respondendo o
+memorando como segunda opinião — e registre onde ela **diverge** do memorando, que é onde
+está o valor. Num caso real, a divergência mudou o alvo do risco: o problema não era perder
+no mérito, era a liminar — *"o processo se ganha, a empresa se perde"* — e a recomendação
+resultante virou requisito de arquitetura (proveniência item a item + kill-switch por fonte,
+impraticável de retrofitar depois).
+
+O aceite deste tipo de teste nunca é "temos um parecer". É **risco classificado + mitigação
+escrita + requisito de arquitetura nomeado**. E o resultado sai marcado como opinião
+simulada, jamais como parecer.
+
+---
+
+## Como isso aparece no placar
+
+- Substituto rodou, instrumento corrigido, fronteira escrita → **PENDENTE, COM SUBSTITUTO
+  DECLARADO**, com o rebaixamento de bloqueio para validação pré-lançamento explícito.
+- A simulação encontrou uma falha **estrutural ou aritmética** que invalida o desenho →
+  **CONFIRMADA, COM ROTA DE SAÍDA QUANTIFICADA**. Falha aritmética vale para humanos também;
+  não precisa de gente para ser verdadeira, e a alavanca medida decide o redesenho.
+- Kit pronto e o humano decidiu recrutar → **EM CURSO**, com data de leitura.
+- Kit pronto e nenhuma decisão tomada → continua **PENDENTE**, listado em "o que continua com
+  o humano", com dono e marco. Pendência sem dono some.
+
+Em todos os casos, o item permanece no placar. Um teste que depende de terceiros não
+desaparece por ser inconveniente: ele muda de estado, com a data em que volta.

package/skills/ll-desarmar/referencias/placar-e-realimentacao.md

@@ -0,0 +1,140 @@
+# Placar, realimentação e fechamento do ciclo
+
+Lido por quem orquestra, em D4 (atribuir veredictos e escrever o placar) e D5 (devolver os
+números ao dossiê e disparar as decisões pré-comprometidas).
+
+---
+
+## Atribuir o veredicto — os casos que confundem
+
+O vocabulário é fechado: cinco veredictos, nenhum inventado, nenhum adjetivo no lugar de um
+deles. A atribuição é sua, depois da auditoria; o executor apenas propõe.
+
+| Situação medida | Veredicto |
+|---|---|
+| Todos os critérios conjuntos passaram, com folga, e a auditoria manteve | **DESARMADA** — com a fronteira de validade escrita: onde vale e onde não vale, com número |
+| Passou o critério de qualidade, reprovou o de cobertura (ou vice-versa) | **DESARMADA COM CONDIÇÕES**, se a condição que faltou vira requisito exequível; **CONFIRMADA** se o critério que reprovou é o que sustentava a tese |
+| 79,7% contra aceite de 80% | **DESARMADA COM CONDIÇÕES**. "No fio" nunca vira aprovação; a condição é o que compensa a margem |
+| Passou porque uma decisão de desenho o sustenta (dedupe, ontologia, guarda, tier de modelo) | **DESARMADA COM CONDIÇÕES**, e a decisão vira requisito nomeado do sistema real |
+| Reprovou, e o teste mediu qual alavanca resolve | **CONFIRMADA, COM ROTA DE SAÍDA QUANTIFICADA** — o resultado de maior valor. Traga a alavanca com número e a decisão de desenho que decorre |
+| Reprovou e nenhuma alavanca testada resolve | **CONFIRMADA** — e o texto diz o que foi testado e não resolveu (isso poupa a próxima rodada). Escale ao humano: é decisão de matar ou redesenhar |
+| Passou no dia 1 de um teste de duração de 14 dias | **EM CURSO** até a data de leitura. Um dia não mede regime contínuo |
+| Simulação rodou no lugar de humanos | **PENDENTE, COM SUBSTITUTO DECLARADO** — salvo quando a simulação achou falha estrutural, aí é CONFIRMADA (ver `humanos-e-substitutos.md`) |
+| O teste não rodou por falta de dado, acesso ou ground truth | Continua **PENDENTE**, com o bloqueio nomeado, dono e marco. Não existe veredicto sem medição |
+
+Dois erros a evitar na hora de escrever: **veredicto sem número** (o veredicto é o rótulo, o
+número é a prova — a linha carrega os dois) e **veredicto que descreve o esforço** ("testado
+extensivamente") em vez do resultado.
+
+---
+
+## Esqueleto do placar
+
+`docs/premortem/placar.md` (ou `docs/desarmar/placar.md` quando não há premortem):
+
+<esqueleto-placar>
+# Placar contra o premortem
+
+> Rodada de {datas}. Testes que não exigem terceiros foram **executados e medidos**
+> ({como: scripts, subagentes, simulação}); os que exigem ficaram pronto-para-disparar.
+> Artefatos reproduzíveis em `{caminho}`. Relatório por teste em `docs/desarmar/resultados/`.
+
+| # | Falha do premortem | Veredicto medido |
+|---|---|---|
+| 1 | {título da falha, com a marca de letalidade} | **{VEREDICTO}** — {os números que decidem} · {fronteira de validade ou alavanca quantificada} · [relatório]({caminho}) |
+
+## Bugs reais encontrados e corrigidos no caminho
+1. **{defeito}** — {o dado real que o expôs} → {correção} → {estado após re-teste}.
+
+## Decisões de arquitetura que os testes cravaram
+- **{decisão}** — {qual teste a cravou e com qual número}; {o que ela obriga no sistema real}.
+
+## O que continua com o humano
+{Reclassificado de bloqueio para validação pré-lançamento, ou mantido como bloqueio.}
+1. **{item}** — dono {nome}, marco {quando}, instrumento pronto em `{caminho}`.
+
+## Custo da rodada
+Orçado {X} × real {Y}, por teste. {Tokens, chamadas de API, horas de conferência manual.}
+</esqueleto-placar>
+
+A linha do placar é lida por alguém que não vai abrir o relatório. Ela precisa carregar a
+conclusão com os números — "**DESARMADA** — 960 questões reais, 4 fontes: 0% de erro no
+campo crítico (316 itens conferidos visualmente); fronteira: só vale no formato sequencial,
+layouts de duas colunas têm 35–100% de erro e ficam fora do MVP" decide sozinha. "Testes
+passaram" não decide nada.
+
+---
+
+## Achados colaterais: por que eles têm seção própria
+
+Testes desenhados para falsear premissas encontram o que nenhuma revisão de código encontra,
+porque são a primeira vez que o sistema encosta em dado real adversarial. Numa rodada real,
+sete falhas previstas renderam **quatro bugs** e **duas decisões de identidade de dados** que
+nenhuma delas antecipava; numa POC anterior, **12 correções estruturais** — chave natural que
+não existe antes do documento oficial, colisão de nomes entre estados, identidade de arquivo
+contaminada por URL assinada volátil, heurística que classificava tipo pelo nome do arquivo e
+acertava 0 de 70.
+
+Isso é resultado esperado, não ruído. Um placar sem achados colaterais sugere que os testes
+não encostaram em dado real o bastante.
+
+---
+
+## Realimentação
+
+### No índice de pesquisas (`docs/README.md`, quando existir)
+
+Regra: **número medido supera número estimado, sem apagar o estimado.**
+
+1. Linha nova na seção correspondente, apontando para o relatório do teste, com a conclusão
+   **e os números** — o mesmo padrão de resumo de uma frase do índice.
+2. **Estado da decisão** reescrito no topo: o que estes testes fecharam, o que abriram, e o
+   que continua em aberto com o teste que o fecha.
+3. **Caveat cruzado** no cabeçalho de todo documento que o teste superou, no formato
+   *"os números de custo deste documento foram medidos em {data} pelo teste {N}: {novo
+   número} contra {antigo}; os mecanismos seguem válidos"*. Não reescreva em silêncio e não
+   delete: o histórico de por que a equipe pensava X importa quando alguém questionar a
+   decisão daqui a seis meses.
+4. Quando um teste desmente uma premissa de alta letalidade do dossiê, ela sai da lista de
+   premissas críticas e entra como fato medido, com a fronteira de validade junto.
+
+### Nas decisões em aberto (`docs/decisoes-em-aberto.md`)
+
+Feche as que o teste resolveu, citando o número e a data. As que continuam abertas ganham o
+motivo — "o teste rodou e não discriminou", "depende de terceiros", "custo maior que o valor
+da informação" — porque decisão que continua aberta sem motivo volta a ser discutida do zero.
+
+### Nas decisões pré-comprometidas
+
+O ramo já estava escrito antes do número existir. Aplique-o como decisão tomada e registre:
+qual ramo disparou, o que ele obriga agora, e o que deixou de ser possível. O valor inteiro
+do pré-compromisso está em não reabrir a discussão depois de ver o dado — é exatamente aí que
+o número ruim seria racionalizado.
+
+### No handoff para a implementação
+
+O que sai desta rodada como **decisão já tomada**, e portanto não é re-perguntado pela skill
+`ll-decidir-antes`: as condições das DESARMADAS COM CONDIÇÕES, os redesenhos das CONFIRMADAS, as
+decisões de arquitetura cravadas pelos testes, e as fronteiras de validade que definem o
+escopo do MVP (o que entra é o que foi medido funcionando; o resto tem data, não promessa).
+
+---
+
+## O ciclo está encerrado quando
+
+- [ ] Cada falha do premortem tem **veredicto medido** com vocabulário fechado — ou está
+      listada como PENDENTE com bloqueio, dono e marco nomeados.
+- [ ] Cada **DESARMADA** traz a fronteira de validade com número, não apenas o "passou".
+- [ ] Cada **CONFIRMADA** traz a alavanca quantificada e a decisão de desenho que decorre.
+- [ ] Cada critério aprovado passou por **auditoria de contexto limpo**, e o resultado da
+      auditoria está registrado — inclusive os "refiz por caminho independente e bate".
+- [ ] Nenhum aceite foi alterado depois do congelamento; os desvios do plano estão escritos
+      com o efeito sobre a validade.
+- [ ] **Achados colaterais** e **correções estruturais** estão registrados com o dado real que
+      os expôs e a recomendação para o sistema real.
+- [ ] **Custo e prazo reais** aparecem contra o orçado, por teste.
+- [ ] Cada decisão pré-comprometida foi **executada** e o que ela obriga está escrito.
+- [ ] Os números voltaram ao índice de pesquisas e às decisões em aberto, com os caveats
+      cruzados nos documentos superados.
+- [ ] O que continua com o humano está explicitamente classificado como **bloqueio** ou
+      **validação pré-lançamento** — nunca deixado ambíguo.

package/skills/ll-orquestrar/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: ll-orquestrar
+description: Regras de orquestração multi-agente — quando delegar a subagentes, como decompor tarefas, escrever briefs precisos, rotear cada etapa para o modelo certo e verificar resultados com evidência. Use antes de qualquer trabalho que envolva subagentes, fan-out paralelo, revisões independentes ou tarefas amplas (auditorias, migrações, features que tocam vários módulos).
+---
+
+# Orquestração e delegação
+
+Ao planejar como executar a tarefa atual, siga estas regras na ordem em que aparecem.
+
+## Quando delegar (e quando não)
+
+- **Agente único primeiro.** Só faça fan-out quando pelo menos um destes valer: os
+  subtrabalhos geram contexto volumoso e irrelevante entre si; o trabalho é genuinamente
+  paralelo em arquivos disjuntos; ou os papéis precisam de independência (implementador
+  vs revisor). O custo escala aproximadamente linear por worker, até ~15× uma sessão
+  simples — gaste onde o resultado compensa.
+- **Escale o esforço à complexidade**: lookup/correção trivial = inline; algumas peças
+  independentes = 2–4 subagentes; varredura ampla ou auditoria = um agente por fatia
+  estreita. Três workers focados vencem cinco dispersos; escopos pequenos são a defesa
+  contra apodrecimento de contexto.
+- **Decomponha por fronteiras de contexto, não por fase.** Um agente é dono de um
+  módulo/página/fatia de ponta a ponta. Evite correntes plano→implementa→testa entre
+  agentes — cada handoff perde fidelidade.
+- **Delegue de forma assíncrona** e continue trabalhando enquanto os subagentes rodam;
+  para subtarefas de acompanhamento sobre o mesmo material, envie mensagem ao agente
+  existente em vez de criar outro (preserva contexto e cache).
+
+## Briefs para subagentes
+
+- **Subagentes não veem nada desta conversa.** Todo brief carrega: objetivo, contrato
+  de saída exato (schema ou formato), caminhos/payloads/restrições verificados, e
+  limites explícitos (o que não tocar). Escreva o brief certo da primeira vez; uma vez
+  delegado, confie — não refaça o trabalho do subagente nem re-derive suas descobertas.
+- **Anatomia de um brief**, nesta ordem: papel em uma frase → contexto e motivação (a
+  tarefa maior, para quem é, o que a saída habilita) → dados/referências → instruções →
+  contrato de saída → limites de escopo → critérios de sucesso. Material longo vai no
+  topo, instruções depois dele. Critérios de sucesso nomeiam verificações explícitas
+  ("rode o typecheck e o build, liste cada rota verificada"), nunca "garanta que
+  funciona" — vagueza convida a declarações prematuras de sucesso.
+- **Delimite conteúdo misto com tags XML** (`<context>`, `<instructions>`, `<input>`,
+  uma tag por tipo de conteúdo). Para documentos longos, peça ao agente para citar as
+  partes relevantes primeiro e agir sobre as citações.
+- **Especificação completa de uma vez.** Modelos atuais rendem melhor recebendo a
+  tarefa inteira e sendo deixados rodar; pingar requisitos aos poucos desperdiça tokens
+  e fidelidade.
+- **Instruções positivas e específicas** ("componha parágrafos de prosa fluida", não
+  "não use markdown"). Teste de ouro: um colega com contexto mínimo, lendo só o prompt,
+  conseguiria fazer a tarefa.
+- **Formato de saída**: declare o schema ou formato diretamente. Prompts de revisão
+  pedem cobertura completa + rótulos de confiança, filtrados depois — "só reporte
+  severidade alta" é seguido ao pé da letra e colapsa o recall.
+- **Não use andaimes de raciocínio**: nada de "pense passo a passo", planos manuais de
+  chain-of-thought, "seja minucioso", "verifique duas vezes" ou instruções repetidas —
+  hoje isso degrada a saída. Um "pense a fundo sobre X" genérico basta.
+
+## Handoffs e contexto
+
+- **Handoff = condensado e estruturado** (≲2k tokens), nunca transcrições. Artefatos
+  pesados (screenshots, relatórios longos, datasets) vão para arquivos; passe caminhos
+  de volta, não conteúdos.
+- **Contexto mínimo eficaz**: o menor conjunto de tokens de alto sinal que alcança o
+  resultado. Dê caminhos e queries e deixe os agentes lerem just-in-time; nunca cole
+  conteúdo de arquivo que o agente pode ler sozinho.
+- Referências ricas (código real, uma suíte de testes, um protótipo) vencem descrições
+  em prosa. Não repita instrução que já está em contexto.
+- **Trabalho de longo horizonte**: externalize estado para arquivos e git. Resumos são
+  um índice do que mudou e de como foi verificado — o detalhe vive no diff e nos
+  commits.
+
+## Roteamento de modelos (roteie cada etapa, não o trabalho inteiro)
+
+Tiers por capacidade e custo — cada tier custa ~2–3× o de baixo:
+Fable > Opus > Sonnet. Sonnet é o piso — não roteie abaixo dele.
+
+- **Fable** — orquestração: decomposição, briefs, julgamentos finais e builds de longo
+  horizonte com verificadores periódicos. Não gaste tokens de Fable em execução.
+- **Opus** — código complexo, refatorações profundas, revisão adversarial onde um
+  defeito perdido vai para produção, debugging não trivial.
+- **Sonnet** — cavalo de batalha padrão: implementação bem especificada, varreduras de
+  revisão contra critérios explícitos, testes, checklists e leitura/extração em massa.
+- Na dúvida entre dois tiers → pegue o mais barato; contexto limpo e brief preciso
+  compram mais qualidade que um modelo maior. Rode etapas mecânicas em esforço baixo.
+
+## Verificação e evidência
+
+- **Verificação com contexto limpo.** Um agente revisor/verificador nunca vê o
+  raciocínio da implementação — ele checa o resultado contra a especificação.
+  Descobertas exigem evidência arquivo:linha; "não encontrei nada" dito claramente é um
+  resultado válido. Para descartar uma descoberta, refute com evidência, não opinião.
+- Valide as afirmações dos subagentes você mesmo com evidência barata (diff, grep
+  focado, um teste dirigido), proporcional ao risco — mais fundo para migrações,
+  contratos de dados, efeitos externos e hot paths.
+- **QA visual/de browser roda dentro de subagentes** — screenshots apodrecem o contexto
+  principal rápido. O agente de QA visualiza cada screenshot que captura (screenshot
+  nunca visto é checagem nunca feita) e retorna só uma lista estruturada de achados.
+- Toda afirmação de "funciona"/"pronto" rastreia a um resultado de ferramenta desta
+  sessão: saída de teste, arquivo:linha, uma query real, um screenshot. Nomeie
+  suposições e o que não foi verificado.
+- Quando um requisito, contrato ou semântica de dados está indefinido, reporte a lacuna
+  e pergunte — nunca preencha com uma interpretação plausível e siga em frente.