wizz-method 1.17.0 → 1.18.0

package/src/skills-lib/cerebro/references/comandos-pesquisa-e-memoria.md

@@ -0,0 +1,96 @@
+# Comandos de Pesquisa e Memoria: /prospect, /memoria
+
+Carregue este arquivo ao executar `/prospect` ou `/memoria`. Antes de tudo, releia a REGRA DE OURO e a seção Vault no SKILL.md principal — esses comandos dependem delas.
+
+## /prospect
+
+**Objetivo:** pesquisar e registrar prospect.
+
+**Passos:**
+1. Receber nome/empresa + objetivo (tudo de uma vez)
+2. Pesquisar via web search (setor, presença digital, dores, oportunidades)
+3. Write direto em `_prospects/YYYY-MM-DD-[slug].md`
+4. Resumo executivo para o usuário (não precisa estar no arquivo)
+
+**Template `_prospects/YYYY-MM-DD-[slug].md`:**
+```markdown
+# [Nome / Empresa]
+> Data: [data] | Objetivo: [tipo] | Status: pesquisado
+
+## Perfil
+- Setor / Tamanho / Produto / Público-alvo
+
+## Presença digital
+- Site / Redes / Ads ativos
+
+## Oportunidade e ângulo de abordagem
+[o que oferecer e como entrar]
+
+## Próximo passo
+- [ ] [ação]
+```
+
+## /memoria
+
+**Objetivo:** ler (e alimentar) a auto-memória do projeto a partir de **qualquer**
+plataforma, não só do Claude Code.
+
+A auto-memória guarda as duas linhas que não moram no vault: **armadilha de stack /
+bug não-óbvio** e **preferência de trabalho / correção do usuário**. No Claude Code ela
+carrega sozinha no início da sessão. Em Codex, OpenCode e Gemini não carrega nada, mas
+o dado está lá: é um diretório comum de arquivos `.md` no disco local. Este comando é a
+ponte de leitura. Não existe segunda cópia dos fatos — a fonte continua sendo uma só.
+
+### Passo 1 — resolver o diretório de memória
+
+```bash
+PROJ_DIR="$(pwd)"
+SLUG="$(printf '%s' "$PROJ_DIR" | sed 's/[/.]/-/g')"
+MEM="$HOME/.claude/projects/$SLUG/memory"
+# fallback: o slug histórico nem sempre normaliza espaço e ponto do mesmo jeito
+[ -d "$MEM" ] || MEM="$(ls -d "$HOME"/.claude/projects/*"$(basename "$PROJ_DIR")"/memory 2>/dev/null | head -1)"
+echo "$MEM"
+```
+
+Diretório inexistente = projeto sem auto-memória. Siga sem travar; não é problema a corrigir.
+
+### Passo 2 — carregar só o índice
+
+```bash
+cat "$MEM/MEMORY.md"
+```
+
+O índice tem teto de 8 KB e é 1 linha por memória. **Nunca leia os arquivos individuais
+em bloco.** Abra um arquivo só quando a linha do índice for relevante ao pedido da vez:
+
+```bash
+grep -rln "termo" "$MEM" --include="*.md" | head -5   # depois Read só o que casar
+```
+
+`_archive/` fica fora do índice de propósito. Só entre nele quando o índice não tiver a resposta.
+
+### Passo 3 — gravar (mesma pasta, mesmo formato)
+
+Vale o Dever de Memória e o teto: **40 memórias e 8 KB de índice por projeto**. Antes de
+criar, `grep` no destino; se o fato já existe, atualize o arquivo que existe.
+
+```markdown
+---
+name: <slug-em-kebab-case>
+description: <resumo de uma linha, é o que decide a relevância na recuperação>
+metadata:
+  type: user | feedback | project | reference
+---
+
+<o fato. Para feedback/project, siga com as linhas **Why:** e **How to apply:**.
+Ligue memórias relacionadas com [[nome-da-outra]].>
+```
+
+Depois de escrever o arquivo, acrescente 1 linha ao `MEMORY.md`:
+`- [Título](arquivo.md) — gancho`
+
+### Limites honestos
+
+- É **pull, não push**: fora do Claude Code nada carrega sozinho, o agente precisa rodar o comando.
+- Vale só para agente rodando na **mesma máquina**. Agente remoto não enxerga este disco.
+- O teto e a poda continuam valendo igual, venha a escrita de qual plataforma vier.

package/src/skills-lib/cerebro/references/comandos-rotina-e-captura.md

@@ -36,19 +36,38 @@ Carregue este arquivo ao executar `/dia`, `/dump`, `/decisao` ou `/conteudo`. An
 
 ## /decisao
 
-**Objetivo:** registrar decisão. Zero reads de arquivos existentes.
+**Objetivo:** registrar decisão. 1 grep antes, nenhum Read.
 
 **Passos:**
 1. Receber descrição + alternativas + projeto (perguntar tudo de uma vez se não passado)
-2. Write direto em `_decisions/YYYY-MM-DD-[slug].md` (template abaixo)
-3. `grep -n "## Decisões recentes" "$VAULT/CEREBRO.md"` → linha
-4. Edit para inserir referência wiki-link logo abaixo dessa linha
-5. Se há projeto: `grep -n "## Decisões" "$VAULT/projetos/$PROJ.md"` → Edit 1 linha
+2. **Grep antes de gravar** (obrigatório, 1 bash call):
+
+```bash
+grep -ril "<2 ou 3 palavras do tema>" "$VAULT/_decisions/" | head -5
+```
+
+- Achou decisão sobre o mesmo tema: **não crie arquivo novo**. Abra o que existe e decida entre dois caminhos:
+  - a decisão nova **substitui** a antiga → marque a antiga com `status: superseded` e `supersedida_por: <slug novo>`, e crie a nova com `supersede: <slug antigo>`
+  - a decisão nova **detalha** a antiga → edite a antiga, não crie a segunda
+- Não achou nada: siga para o passo 3.
+
+3. Write direto em `_decisions/YYYY-MM-DD-[slug].md` (template abaixo)
+4. `grep -n "## Decisões recentes" "$VAULT/CEREBRO.md"` → linha
+5. Edit para inserir referência wiki-link logo abaixo dessa linha
+6. Se há projeto: `grep -n "## Decisões" "$VAULT/projetos/$PROJ.md"` → Edit 1 linha
 
 **Template `_decisions/YYYY-MM-DD-[slug].md`:**
 ```markdown
+---
+data: YYYY-MM-DD
+projeto: [nome]
+tema: [2 a 4 palavras-chave separadas por vírgula, é por elas que o grep acha]
+status: ativa
+supersede: [slug da decisão que esta substitui, ou omitir]
+supersedida_por: [preenchido depois, quando outra decisão substituir esta]
+---
+
 # [Título]
-> Data: [data] | Projeto: [[projetos/nome]] | Status: ativa
 
 ## Decisão
 [1-2 linhas]

package/src/skills-lib/cerebro/references/comandos-sessao.md

@@ -2,11 +2,30 @@
 
 Carregue este arquivo ao executar `/iniciar`, `/ver` ou `/salvar`. Antes de tudo, releia a REGRA DE OURO e a seção Vault no SKILL.md principal — esses comandos dependem delas.
 
+## O bloco Estado
+
+Todo arquivo em `projetos/` começa com um bloco `## Estado` de no **máximo 12 linhas**, logo abaixo do título. Ele é sobrescrito a cada `/salvar` e é a única coisa que o `/ver` precisa ler.
+
+```markdown
+## Estado
+- **Fase:** [em que ponto o projeto está, 1 linha]
+- **Stack:** [1 linha]
+- **Onde parou:** [1 linha]
+- **Próximo passo:** [1 linha, a primeira coisa a fazer ao voltar]
+- **Bloqueio:** [1 linha, ou "nenhum"]
+- **Última sessão:** [YYYY-MM-DD] — [1 linha]
+```
+
+Por que 12 linhas: o `/ver` vira 1 Read de 14 linhas em vez de um tail de 60. E o bloco fica no topo, onde qualquer humano abrindo a nota também lê primeiro.
+
+O que **não** entra no bloco: histórico, decisão, aprendizado, lista longa de pendências. Histórico é a tabela `Sessões`; decisão é `_decisions/`; aprendizado é a auto-memória do agente; a lista completa de pendências é a seção `O que falta`.
+
 ## /iniciar
 
 **Objetivo:** configurar projeto novo. Só cria arquivos — não lê nada além do CEREBRO.md mínimo.
 
 **Passos:**
+
 1. Descobrir vault (ver seção Vault)
 2. `grep -c "$PROJ" "$VAULT/CEREBRO.md"` → verificar se projeto já existe (0 = novo)
 3. Se novo: entrevistar em 1 mensagem (organização, info essencial, estilo, modo)
@@ -15,21 +34,27 @@ Carregue este arquivo ao executar `/iniciar`, `/ver` ou `/salvar`. Antes de tudo
 6. Confirmar
 
 **Template `projetos/[nome].md`:**
+
 ```markdown
 # [Nome] — Estado Atual
 > Atualizado: [data]
 
+## Estado
+- **Fase:** [fase]
+- **Stack:** [stack]
+- **Onde parou:** [1 linha]
+- **Próximo passo:** [1 linha]
+- **Bloqueio:** nenhum
+- **Última sessão:** [data] — [1 linha]
+
 ## Preferências
 - Organização: [resposta]
 - Info essencial: [resposta]
 - Estilo: [resposta]
 - Modo: [registro / sugestivo]
 
-## Stack
-[breve descrição]
-
-## Onde parou
--
+## Contexto
+[o que o bloco Estado não cabe: stack detalhada, restrições, links]
 
 ## O que falta
 - [ ]
@@ -41,6 +66,7 @@ Carregue este arquivo ao executar `/iniciar`, `/ver` ou `/salvar`. Antes de tudo
 ```
 
 **Template bloco em CEREBRO.md:**
+
 ```markdown
 ### [Nome] [emoji]
 - **Stack:** [stack]
@@ -51,20 +77,14 @@ Carregue este arquivo ao executar `/iniciar`, `/ver` ou `/salvar`. Antes de tudo
 
 ## /ver
 
-**Objetivo:** mostrar estado atual rápido. Máximo: 1 Read.
+**Objetivo:** mostrar estado atual rápido. Máximo: 1 Read de 14 linhas.
 
 **Passos:**
-1. `wc -l "$VAULT/projetos/$PROJ.md"` → total de linhas
-2. Read com `offset=(n-60)`, `limit=60` → pega Onde parou + O que falta + Sessões
-3. Retornar em formato condensado:
 
-```
-## [Projeto] — [data última sessão]
-Stack: [1 linha]
-Onde parou: [bullets]
-O que falta: [checkboxes]
-Última sessão: [1 linha]
-```
+1. Read `projetos/[nome].md` com `limit=14` (o bloco Estado está no topo)
+2. Devolver o bloco quase como está, sem reescrever
+
+**Arquivo antigo, sem bloco Estado no topo:** cai no caminho lento uma única vez — `wc -l` e Read das últimas 60 linhas — e ao devolver, ofereça criar o bloco. Aceito, o próximo `/ver` volta a custar 1 Read curto.
 
 ## /salvar
 
@@ -73,6 +93,7 @@ O que falta: [checkboxes]
 **Passos (executar em ordem, sem desvios):**
 
 **1. Localizar projeto e bloco no CEREBRO.md (1 bash call)**
+
 ```bash
 VAULT=~/Documents/projects/Obsidian\ Vault
 PROJ=construcao   # inferir do diretório atual ou contexto
@@ -80,43 +101,46 @@ grep -n "### \|Última sessão\|Pendente" "$VAULT/CEREBRO.md" | grep -A2 -i "$PR
 wc -l "$VAULT/projetos/$PROJ.md"
 ```
 
-**2. Ler apenas o final do arquivo do projeto (1 Read)**
-- `offset = (total_linhas - 80)`, `limit = 80`
-- Isso captura: Hoje atual, Onde parou, O que falta, tabela Sessões
+**2. Ler o topo e o fim do arquivo do projeto (2 Reads curtos)**
+
+- topo: `limit=14` → bloco Estado
+- fim: `offset = (total_linhas - 40)`, `limit = 40` → O que falta e tabela Sessões
 
 **3. Construir as alterações na memória, depois aplicar (Edits atômicos)**
 
-Em `projetos/[nome].md`, sempre adicionar ACIMA da seção "Onde parou" existente:
+Em `projetos/[nome].md`:
+
+- **Sobrescrever o bloco `## Estado`** inteiro, mantendo os mesmos 6 campos e o teto de 12 linhas. Não empilhar bloco novo: o histórico é a tabela.
+- Atualizar a seção `O que falta` (marcar o que saiu, acrescentar o que entrou).
+- Acrescentar 1 linha ao fim da tabela `Sessões`:
+
 ```markdown
-## Hoje ([data] — [sessão])
-- [item 1]
-- [item 2]
+| [data] | [resumo 1 linha] |
 ```
 
-Substituir "Onde parou" e "O que falta" com o estado novo.
-
-Adicionar linha na tabela Sessões (append na última linha da tabela).
+Arquivo sem bloco `## Estado`: criar agora, logo abaixo do título, com o que a sessão apurou.
 
 **4. Atualizar bloco do projeto em CEREBRO.md (1 Edit)**
+
 - Usar grep do passo 1 para saber as linhas exatas
 - Edit cirúrgico apenas nas linhas "Última sessão" e "Pendente"
 
-**5. Atualizar CONTEXT.md (Edit cirúrgico — só campos alterados)**
-- Nunca reescrever o arquivo inteiro
-- Editar apenas: data no cabeçalho, pendências em "O que falta", commit hash se mudou
+**5. Se houve decisão relevante:** criar arquivo em `_decisions/` (ver `comandos-rotina-e-captura.md` para o frontmatter e a regra de grep-antes-de-gravar).
+Aprendizado técnico (armadilha de stack, bug não óbvio, pegadinha de ambiente) **não vai para o vault**: vai para a auto-memória do agente. No vault ninguém lia. No Claude Code ela carrega sozinha no início da sessão; em Codex, OpenCode e Gemini o caminho de leitura é o `/memoria` (ver `comandos-pesquisa-e-memoria.md`).
 
-**6. Append em `_index/sessions.md` (1 Edit ou Write se não existir)**
-```markdown
-| [data] | [projeto] | [resumo 1 linha] |
-```
-
-**7. Se houve decisão ou aprendizado relevante:** criar arquivo em `_decisions/` ou `_learnings/` (Write direto, sem Read prévio).
+**6. Higiene do índice (compactação)**
 
-**8. Higiene do índice (compactação)**
 ```bash
 wc -l "$VAULT/CEREBRO.md"
 ```
+
 - Se > 150 linhas: mover o conteúdo mais antigo/menos essencial (projeto ✅ concluído ou ❌ descontinuado com histórico longo, ou entradas de "Decisões recentes" além das ~15 mais novas) para `_index/cerebro-archive.md`, deixando no lugar só 1 linha de referência `[[_index/cerebro-archive]]`. Nunca apagar, só mover.
 - Se ≤ 150 linhas: pular este passo.
 
-**9. Confirmar em 2 linhas** o que foi salvo.
+```bash
+grep -c "^| " "$VAULT/projetos/$PROJ.md"
+```
+
+- Tabela Sessões com mais de 15 linhas: mover as mais antigas para `_index/cerebro-archive.md`, sob `## Sessões antigas — [projeto]`, deixando as 15 mais novas no arquivo do projeto. Nunca apagar, só mover.
+
+**7. Confirmar em 2 linhas** o que foi salvo.

package/src/skills-lib/premium-landing-ui-researcher/references/source-first-protocol.md

@@ -35,7 +35,7 @@ Antes de qualquer rede ou MCP, inspecionar o que o usuário já tem:
 
 1. **Pasta `modelos lp/` (ou equivalente)**: rodar `find ~ -maxdepth 6 -type d -iname "modelos*lp*"` para localizar. Listar subpastas, ler package.json e README.md de cada projeto promissor. Identificar quais já tem Lenis, GSAP, R3F, OGL, Embla, Framer Motion, shaders prontos.
 2. **Projeto atual do usuário**: se houver, listar dependências instaladas (`cat package.json`) e componentes/utilities existentes que podem ser reaproveitados.
-3. **Cérebro / vault do usuário**: usar grep nos arquivos do vault (`projetos/`, `_learnings/`) para achar padrões técnicos já documentados em projetos anteriores.
+3. **Cérebro / vault do usuário**: usar grep nos arquivos do vault (`projetos/`, `_decisions/`) para achar padrões técnicos já documentados em projetos anteriores.
 
 Saída desta fase: lista de **componentes, libs e padrões reaproveitáveis** com path absoluto.
 

package/src/skills-lib/tracking-audit/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: tracking-audit
+description: Auditoria e diagnóstico de rastreamento de resposta direta em dois modos. Modo implantação valida pixel, CAPI, domínio verificado, eventos priorizados, template de UTM com ID, repasse do parâmetro nativo pelo checkout, higiene de nomenclatura e compra-teste por caminho. Modo diagnóstico lê as transições do funil contra a régua, separa problema de medição de problema de conversão e diz qual transição está furando. Use quando alguém perguntar "por que a venda não bate com o gerenciador", "onde está furando o funil", "meu pixel está certo?", "as UTMs estão corretas?", "o tráfego orgânico está inflado", "qual dado falta pra eu decidir", ou antes de subir campanha nova. NÃO use para desenhar plano de medição de SaaS/produto (use analytics-tracking), para decidir bid e orçamento (use paid-ads) nem para criar a oferta (use wizz-offer-forge).
+---
+
+# Tracking Audit
+
+Auditoria de rastreamento para oferta de resposta direta. Uma hora aqui evita 30 dias de campanha medida errado.
+
+A skill faz duas coisas e nada além: **valida o que foi instalado** e **diz onde o funil está furando**. Ela não cria oferta, não decide bid e não escreve copy.
+
+## Passo 0 — Achar a régua (obrigatório, sempre)
+
+Benchmark sem origem é chute. Antes de qualquer análise, resolva de onde vêm os números, nesta ordem:
+
+1. **Skill `lowticket-metodologia` instalada?** Se sim, ela tem precedência. Leia a entrada de diagnóstico de funil no INDEX dela e use os benchmarks de lá. Declare na resposta: "régua: metodologia low ticket".
+2. **O projeto tem histórico próprio?** Trinta dias de dados reais do mesmo público valem mais que qualquer benchmark de mercado. Use a mediana do próprio histórico como linha de base.
+3. **Nenhum dos dois?** Peça ao usuário. Não invente faixa, não use número de memória, não cite benchmark sem dizer de onde saiu.
+
+> Regra anti-invenção: todo número que aparecer no relatório tem fonte declarada, ou vira PENDÊNCIA. Um relatório com faixa inventada é pior que nenhum relatório, porque parece medido.
+
+## Escolher o modo
+
+| O pedido é... | Modo | Referência |
+|---|---|---|
+| Vou subir campanha, está tudo instalado? | implantação | `references/modo-implantacao.md` |
+| Está rodando e o número não fecha | diagnóstico | `references/modo-diagnostico.md` |
+| A venda não bate com o gerenciador | diagnóstico, começando por atribuição | `references/utm-e-atribuicao.md` |
+| Como monto as UTMs desta conta | implantação, só a parte de tags | `references/utm-e-atribuicao.md` |
+
+Em dúvida entre os dois: se existe dado rodando, é diagnóstico. Implantação é para o que ainda não subiu.
+
+## Os princípios que decidem no empate
+
+- **O banco próprio é a fonte de verdade.** Gerenciador e Analytics perdem venda (bloqueador, iOS, cookie recusado). O número oficial vem do banco alimentado por webhook da plataforma de pagamento. Quando as duas fontes divergem, a divergência é o achado, não um erro de leitura.
+- **O pixel mede o pixel.** Connect rate é o instante em que o `PageView` dispara, não o instante em que a pessoa vê a oferta. Subir o pixel sem consertar a página é maquiagem de métrica.
+- **Atribuir por ID, não por nome.** A UTM carrega nome e ID. Renomear campanha não pode quebrar a atribuição.
+- **Orgânico não é canal, é ausência de UTM.** O balde "organic" é destaque sem tag, direct e recompra. Taguear tudo e ver o orgânico cair é a prova da origem real.
+- **Higiene de nomenclatura é infraestrutura.** Nome de campanha sujo não se conserta depois: a plataforma continua servindo o nome antigo em cache para o que já foi entregue.
+- **Diagnóstico é do fim para o começo.** Sempre. Recuperar venda iniciada é dinheiro que já era seu; mexer em criativo com checkout furando é desperdício.
+
+## Entradas que a auditoria precisa
+
+Peça de uma vez, não uma por uma:
+
+- URL da página de vendas e da página de checkout
+- Plataforma de checkout e de pagamento
+- Print ou export do gerenciador com: cliques no link, visitas à página, checkouts iniciados, compras, valor gasto, valor atribuído
+- Acesso (ou print) do painel de atribuição, quando existir
+- O template de UTM que está colado hoje no campo de parâmetros de URL
+
+Faltou item: siga com o que dá e liste o que falta em PENDÊNCIAS. Nunca preencha buraco de dado com estimativa.
+
+## Saída
+
+Um relatório em markdown, sempre com estas quatro partes:
+
+1. **Achados por severidade.** `CRÍTICO` (o dado está errado e a decisão em cima dele também), `ALTO` (perde venda ou perde atribuição), `MÉDIO` (higiene, vai doer depois), `BAIXO` (melhoria).
+2. **A transição que está furando**, com a taxa real calculada e a régua ao lado, sempre com a fonte da régua.
+3. **O que consertar, em ordem**, seguindo a hierarquia do modo diagnóstico. Um item por linha, com quem resolve (dev, checkout, criativo, página).
+4. **Plano de tags pronto para colar**, quando o modo for implantação ou quando a auditoria encontrar UTM errada.
+
+Feche com **PENDÊNCIAS**: o que não deu para verificar e o que precisa de acesso ou de dado que não veio.
+
+## Ferramentas
+
+- Inspeção de página: CLI `agent-browser`. Nunca Playwright.
+- Nada mais é obrigatório. A auditoria funciona lendo print e página.
+
+## Quando delegar
+
+| Situação | Vai para |
+|---|---|
+| O furo é a página (LCP, mobile, blocos) | `page-cro` |
+| O furo é o criativo | `ad-creative` |
+| O furo é bid, orçamento ou estrutura de campanha | `paid-ads` |
+| Precisa desenhar medição de produto ou SaaS | `analytics-tracking` |
+| A oferta em si não fecha | `wizz-offer-forge` |

package/src/skills-lib/tracking-audit/references/modo-diagnostico.md

@@ -0,0 +1,72 @@
+# Modo diagnóstico
+
+Está rodando e o número não fecha. Este modo descobre **qual transição está furando** e separa problema de medição de problema de conversão.
+
+Régua: leia o Passo 0 do `SKILL.md`. Cada faixa citada no relatório declara de onde veio.
+
+## As 5 transições
+
+Base do funil é a visita à página, igual a 100%. A taxa real de cada transição é a etapa dividida pela **anterior**, nunca pela base.
+
+| # | Transição | O que ela revela |
+|---|---|---|
+| 1 | Cliques no anúncio → Visitas na página | Saúde técnica: velocidade, redirect, SSL, mobile, disparo do `PageView` |
+| 2 | Visitas → Checkout iniciado | Casamento entre criativo, página e oferta |
+| 3 | Checkout iniciado → Venda iniciada | Atrito de checkout: campos, meios de pagamento, frete, taxa surpresa |
+| 4 | Venda iniciada → Aprovada (PIX) | Recuperação: lembrete, prazo, instrução |
+| 5 | Venda iniciada → Aprovada (cartão) | Recusa: antifraude, parcelamento, emissor |
+
+Sempre diagnosticar **do fim para o começo**.
+
+## Hierarquia do que atacar primeiro
+
+Se dá para mexer em uma coisa só:
+
+1. **Venda iniciada → aprovada.** O ROI mais rápido do funil. Esse dinheiro já era seu.
+2. **Checkout iniciado → venda iniciada.** Ajuste barato, ganho grande.
+3. **Visitas → checkout.** Página e criativo. Mais lento e mais caro; só depois que o checkout está resolvido.
+4. **Cliques → visitas.** Técnico. Chama dev.
+
+Ordem de prioridade das métricas: vendas > checkout iniciado > CPC > hook rate > hold rate > CPM. Não se mexe em CPC se a página não converte. Não se mexe em CPA se o checkout está furando.
+
+## Medição contra conversão
+
+Antes de dizer "a conversão caiu", prove que a **medição** está de pé. As três perguntas:
+
+| Sintoma | Se for medição | Se for conversão |
+|---|---|---|
+| Cliques muito acima das visitas | `PageView` não dispara, ou dispara tarde | Página fora do ar, redirect quebrado |
+| Venda no banco e não no gerenciador | Falta CAPI, falta domínio verificado, iOS | Nada: a venda existe |
+| Venda no gerenciador e não no banco | Deduplicação ausente, evento duplicado | Nada: a venda não existe |
+| Orgânico subindo sozinho | Rota sem UTM | Recompra e boca a boca de verdade |
+| Atribuição some ao renomear campanha | Atribuição por nome, não por ID | Nada |
+
+Regra prática: se as duas fontes discordam, a discordância **é** o achado. Nunca escolha a fonte que confirma a tese.
+
+## Qual dado falta para decidir
+
+Parte do trabalho é dizer o que não dá para responder ainda. Formato:
+
+```
+PENDÊNCIA: não dá para separar atrito de checkout de desistência de preço.
+Falta: evento AddPaymentInfo.
+Custo de instalar: baixo.
+O que muda quando existir: a transição 3 vira duas, e o conserto deixa de ser chute.
+```
+
+Nunca invente o número que falta. Um "provavelmente uns 30%" contamina a decisão inteira.
+
+## ROI verdadeiro contra ROI falso
+
+- **ROI falso:** valor atribuído pelo gerenciador dividido pelo gasto do gerenciador. Conta venda que não entrou e ignora venda que entrou sem atribuição.
+- **ROI verdadeiro:** faturamento aprovado no banco próprio, menos taxa da plataforma e menos reembolso, dividido pelo gasto real do período.
+
+Sempre reporte os dois lado a lado. A diferença entre eles é o tamanho do buraco de medição.
+
+## Leitura de print do gerenciador
+
+Métricas que precisam aparecer no print para o diagnóstico rodar:
+
+cliques no link, visualizações da página, checkouts iniciados, compras (ou resultados quando a campanha otimiza para compra), valor gasto, valor atribuído.
+
+Faltou alguma: diga qual e o que ela impede de calcular. Não estime.

package/src/skills-lib/tracking-audit/references/modo-implantacao.md

@@ -0,0 +1,89 @@
+# Modo implantação
+
+Checklist executável para antes de subir campanha. Roda de cima para baixo. Cada item tem um jeito de verificar, não é declaração de fé.
+
+Régua: leia o Passo 0 do `SKILL.md` antes. Sem régua declarada, o relatório sai sem número.
+
+## 1. Página e carregamento
+
+| Verificar | Como | Reprova quando |
+|---|---|---|
+| Página abre no mobile real | `agent-browser` em viewport de celular | Layout quebra ou bloco some |
+| Tempo até o conteúdo principal | PageSpeed Insights, aba mobile | Fora da meta declarada pela régua do projeto |
+| Redirect | Abrir o link do anúncio sem encurtador no meio | Qualquer salto extra ou loop |
+| SSL | Cadeado e certificado válido no domínio final | Aviso do navegador |
+
+Furou aqui: é trabalho de dev. Não mexa em criativo antes de resolver.
+
+## 2. Pixel e servidor
+
+| Verificar | Como | Reprova quando |
+|---|---|---|
+| Pixel presente na página | Extensão de debug da plataforma ou console | Não dispara `PageView` |
+| Posição do disparo | Ver se o `PageView` sobe antes do conteúdo visível | Dispara em `onload` tardio: infla connect rate e mente sobre a visita |
+| Evento de conversão do lado do servidor (CAPI) | Painel de qualidade da plataforma | Só navegador, sem servidor |
+| Deduplicação | `event_id` igual entre navegador e servidor | Sem `event_id`: a mesma venda conta duas vezes |
+| Domínio verificado | Painel de negócio da plataforma | Não verificado: perde atribuição em iOS |
+
+> O pixel mede o pixel. Um connect rate bonito com página lenta é métrica maquiada, não conversão.
+
+## 3. Eventos priorizados
+
+Instale nesta ordem. Os quatro primeiros são obrigatórios; os outros entram quando o funil tiver a etapa.
+
+1. `PageView` — visita à página de vendas
+2. `ViewContent` — chegou ao bloco de oferta (não é o mesmo que abrir a página)
+3. `InitiateCheckout` — clicou para comprar
+4. `Purchase` — venda aprovada, com valor e moeda
+5. `AddPaymentInfo` — preencheu pagamento, separa atrito de checkout de desistência de preço
+6. `Lead` — captura, quando existir etapa de lead
+7. `Subscribe` ou evento de recorrência, quando existir
+8. Evento próprio de upsell ou order bump, quando existir
+
+Regra: evento sem valor monetário em `Purchase` inutiliza ROAS. Evento duplicado inutiliza tudo.
+
+## 4. Tags e atribuição
+
+Ver `utm-e-atribuicao.md` para os templates. O que a implantação precisa provar:
+
+- O template de UTM está colado no campo de parâmetros de URL do anúncio, não no destino do anúncio.
+- Cada parâmetro carrega nome **e** ID.
+- O parâmetro nativo da plataforma de checkout (quando existir) recebe a mesma informação empacotada, porque o checkout nem sempre repassa `utm_*`.
+- Nenhum nome de campanha, conjunto ou anúncio contém `|`, `#`, `&` ou `?`.
+- O padrão de nomenclatura está escrito em algum lugar que a próxima pessoa lê.
+
+## 5. Repasse pelo checkout
+
+Este é o item que mais falha e o mais fácil de esquecer.
+
+1. Abra a página com uma UTM de teste na URL.
+2. Clique para comprar.
+3. Na página de checkout, confirme que os parâmetros chegaram (URL, campo escondido ou painel da plataforma).
+4. Confirme que o webhook de venda entrega esses parâmetros para o destino final (banco, planilha, painel de atribuição).
+
+Quebrou entre 2 e 3: o checkout não repassa. Use o parâmetro nativo.
+Quebrou entre 3 e 4: o problema é a integração, não a tag.
+
+## 6. Compra-teste por caminho
+
+Cada rota de entrada recebe uma compra real de teste antes de investir:
+
+- anúncio
+- link da bio
+- story
+- destaque
+- direct ou conversa
+
+Para cada rota, registre: a venda apareceu no banco, apareceu no painel de atribuição, e apareceu com a origem certa. Rota que não passa nas três é rota cega.
+
+## 7. Fechamento
+
+Antes de liberar a subida, o relatório precisa responder sim para as cinco:
+
+1. A visita é medida no instante certo?
+2. A venda chega ao banco próprio?
+3. A venda sabe de qual anúncio veio, por ID?
+4. O orgânico é o que sobra depois de tudo taguear, e não um balde de preguiça?
+5. Existe pelo menos uma compra-teste aprovada por rota?
+
+Qualquer "não" vira achado `CRÍTICO` ou `ALTO`. Nada sobe com um `CRÍTICO` aberto.

package/src/skills-lib/tracking-audit/references/utm-e-atribuicao.md

@@ -0,0 +1,75 @@
+# UTM e atribuição
+
+O cimento de todo o resto. Se a tag está errada, o funil inteiro mede ficção.
+
+## A regra central
+
+Cada parâmetro carrega **nome e ID**, separados por um delimitador fixo. O nome existe para humano ler; o ID existe para a atribuição sobreviver a renomeação.
+
+```
+utm_campaign={{campaign.name}}|{{campaign.id}}
+utm_medium={{adset.name}}|{{adset.id}}
+utm_content={{ad.name}}|{{ad.id}}
+utm_term={{placement}}
+utm_source=<plataforma>
+```
+
+Cole no campo **parâmetros de URL** do anúncio, nunca no destino.
+
+## Redundância no parâmetro nativo
+
+Muito checkout não repassa `utm_*` para o webhook de venda. Quando a plataforma de checkout tem parâmetro próprio (por exemplo `xcod`, `src` ou `sck`), empacote a mesma informação lá também, com um separador longo e improvável:
+
+```
+xcod=<origem><SEP><campaign.name>|<campaign.id><SEP><adset.name>|<adset.id><SEP><ad.name>|<ad.id><SEP><placement>
+```
+
+O separador precisa ser uma string que nunca apareça em nome de campanha. Escolha uma vez e nunca mude: mudar quebra o histórico.
+
+## Delimitadores proibidos em nomes
+
+Nunca use `|`, `#`, `&` ou `?` em nome de campanha, conjunto ou anúncio. São delimitadores da própria string de tag.
+
+Violou: **recriar a campanha**. Renomear não resolve, porque a plataforma continua servindo o nome antigo em cache para as impressões já entregues.
+
+Padrão de nome que não dá problema: minúscula, sem acento, palavras separadas por hífen ou underscore, campos em ordem fixa. Escreva o padrão em algum lugar. Padrão que só existe na cabeça de alguém não é padrão.
+
+## Outras plataformas
+
+O formato é o mesmo em toda plataforma de mídia: macro nativa da plataforma preenchendo `utm_*`, mais o empacotamento no parâmetro nativo do checkout quando ele existir.
+
+| Plataforma | O que muda |
+|---|---|
+| Meta | Macros `{{campaign.name}}`, `{{campaign.id}}`, `{{adset.*}}`, `{{ad.*}}`, `{{placement}}` |
+| Google | Macros entre chaves simples, mais `{lpurl}?` na frente e `keyword`, `device`, `network` |
+| TikTok, Kwai, Taboola | Mesma estrutura, nomes de macro próprios da plataforma |
+
+Antes de escrever o template de uma plataforma, confirme o nome exato da macro na documentação dela. Macro errada entrega a string literal `{{campaign.id}}` na URL, e ninguém percebe até a primeira venda.
+
+Existe variação a mais quando há cloaker na frente do checkout: um conector extra para não quebrar a string. Confirme com quem instalou o cloaker.
+
+## O balde do orgânico
+
+"Orgânico" não é canal. É tudo que chegou sem tag: destaque do Instagram sem UTM, link na bio sem UTM, direct, recompra, boca a boca.
+
+Diagnóstico: tague **todas** as rotas próprias (bio, destaque, story, direct, e-mail, grupo) e observe o orgânico cair. O que sobrar depois disso é orgânico de verdade. O tamanho da queda é a prova de quanto o balde estava mentindo.
+
+Padrão sugerido para rota própria:
+
+```
+utm_source=instagram&utm_medium=<bio|destaque|story|direct>&utm_campaign=<nome-do-destaque-ou-post>
+```
+
+## Primeiro toque
+
+Último clique é o padrão de quase toda ferramenta, e ele esconde qual anúncio **apresentou** a oferta. Guarde o primeiro toque no seu banco (primeira UTM vista pelo visitante, com data) e compare com o último. Multi-toque simples, dois campos, resolve a maior parte das decisões de criativo.
+
+## Conferência rápida
+
+Cinco checagens que pegam quase todo erro de tag:
+
+1. Abra o anúncio em preview e leia a URL final: tem macro literal sobrando?
+2. A UTM sobrevive ao redirect até o checkout?
+3. O webhook de venda entrega os campos ao banco?
+4. Dois anúncios diferentes geram `utm_content` diferentes?
+5. Renomear um anúncio quebra a atribuição? Se quebrar, está atribuindo por nome.