Verdade do Produto
Um vídeo de produto que mostra algo que o produto não pode fazer é pior do que nenhum vídeo. Na produção de onde estas skills vêm, os momentos mais custosos foram todos de falhas de verdade: um badge construído à mão com o tamanho errado e o nome de produto errado, um fluxo de trabalho narrado como "aguardando o resultado da chamada" quando o produto só retorna resultados por meio de um trigger separado, uma chamada de teste rotulada como uma reserva confirmada que ninguém havia verificado de ponta a ponta, e um documento da empresa cujo título contradizia o posicionamento que a equipe havia acordado. Cada um foi pego tarde, por um revisor, e custou uma versão.
Esta skill torna a verificação explícita e mecânica: cada linha e cada tela ganha uma linha em
TRUTH.md com uma fonte, e truth_check.py recusa um vídeo onde qualquer linha está faltando, desatualizada ou
sem suporte.
Entradas
videos/<video>/audio/lines.tsv(a narração, uma frase por id de linha)videos/<video>/SOURCES.md(de source-recon: as telas e seu código)videos/<video>/BRIEF.md,COVERAGE.md,CLAIMS.md(o que o vídeo deve explicar, o posicionamento, frases a evitar, afirmações que precisam de aprovação)product.yaml:positioning,never_say,names(nome canônico para strings legadas),banned_termssources/<role>/esources.lock(fixado por source-recon; se faltar, execute source-recon primeiro, porque as citações devem apontar para o commit travado)
1. Liste as afirmações
Divida cada linha de lines.tsv nas afirmações que ela faz. "Acme Tasks lê seu calendário e move tarefas atrasadas para amanhã" são duas afirmações: ela lê o calendário, e ela move tarefas atrasadas. Adicione uma afirmação por tela e por ação na tela de SOURCES.md e dos capítulos ("Clicar em Planejar meu dia abre o planejador com três sugestões").
Escreva as perguntas que essas afirmações levantam, formuladas para que o código possa respondê-las: o que dispara isso, o que é armazenado, quais opções existem, o que o usuário vê e onde, o que acontece apenas no servidor.
2. Responda a partir do código e da documentação
Lance subagentes somente leitura em paralelo, um por área do produto (comportamento frontend, cada backend,
documentação), com o prompt em references/product-facts-prompt.md. Aponte-os para sources/<role>/,
nunca para o checkout do usuário, para que seus números de linha correspondam ao lock. Eles respondem apenas a partir do código
ou documentação, citam cada fato, e dizem "não encontrado" em vez de adivinhar.
3. Classifique cada afirmação
| visibilidade | significa | o vídeo pode |
|---|---|---|
ui | Renderizado pelo frontend; cite o template ou linha i18n | mostrá-lo e narrá-lo |
backend | Verdadeiro no servidor, nada na tela mostra isso | narrá-lo, nunca desenhar uma UI para ele |
docs | Apenas a documentação diz isso | narrá-lo com a URL da documentação; verificar se o código concorda quando possível |
mock | Uma peça projetada, não UI do produto (tela de chamada telefônica, cartão final, texto gerado) | mostrá-lo, marcado como projetado no BRIEF |
| veredito | significa |
|---|---|
backed | a fonte diz exatamente isso |
approved | precisava de aprovação (restrito, não lançado, uma afirmação listada em CLAIMS.md) e o revisor a deu em CLAIMS.md |
needs-approval | verdadeiro, mas restrito, com gate, não lançado ou listado em CLAIMS.md; aguardando o revisor |
rewrite | parcialmente verdadeiro; você propõe uma redação com suporte nas notas |
cut | não verdadeiro, ou nenhuma fonte encontrada |
unbacked | não verificado ainda |
mock | apenas com visibilidade mock |
Apenas backed e approved passam para linhas narradas. Um recurso restrito (visível apenas para alguns
papéis, planos ou equipes internas), um recurso atrás de uma flag, ou um em um branch não mesclado é
needs-approval até que o revisor diga sim em CLAIMS.md, e o BRIEF observa que está
restrito. Isso aconteceu na produção de origem: um recurso que apenas funcionários internos podiam ver foi
mostrado a pedido do revisor, e marcado.
4. Corrija o que não se sustenta
- Reescreva uma frase parcialmente verdadeira na versão mais forte que a fonte suporta. Mantenha o significado que o escritor queria; mude os mecanismos para os reais.
- Corte o que não tem fonte. Não o suavize em algo vago; afirmações vagas ainda são afirmações.
- *Nunca deixe um rótulo se desviar. Uma peça projetada marcada como "ilustrativa" não deve perder esse rótulo por estética depois sem reverificar a afirmação que a versão sem rótulo faz.
- Posicionamento vence documentos. Se um deck ou PRD diz algo que
never_sayou CLAIMS.md proíbe, a regra vence e a frase muda. - Apenas nomes atuais. Use os nomes canônicos em
product.yaml names, mesmo quando a UI ativa ou o código ainda mostra uma string legada. Pesquise em lines.tsv, especificações e templates por cada string legada e cada entrada debanned_terms(concorrentes, fornecedores terceiros que a equipe mantém fora de tela, clientes reais) e corrija cada ocorrência.
5. Quando uma solicitação entra em conflito com o produto
Quando o briefing ou o revisor pede algo que o código não suporta, não construa um falso e não o descarte silenciosamente. Faça uma pergunta fechada com opções e um padrão recomendado, e mantenha no máximo três dessas perguntas por rodada, porque listas abertas de vetos não são respondidas e o silêncio se torna uma decisão que ninguém tomou. O padrão "apenas o que é real":
O briefing mostra o Acme Tasks reservando a sala de reunião ele mesmo. O código apenas cria a tarefa e vincula o calendário da sala (frontend/src/rooms/LinkRoom.tsx:22@1a2b3c4); a reserva acontece no aplicativo de calendário. Qual deles?
- Apenas o que é real (recomendado): mostre a etapa de vinculação e diga "vincula o calendário da sala".
- Mostre a tela de reserva do aplicativo de calendário como uma peça projetada, rotulada, e narre-a como a etapa do calendário.
- Descarte o trecho.
Registre a resposta em CLAIMS.md e defina o veredito a partir dela.
6. Escreva TRUTH.md
# Verdade: <video>
Travado: frontend main@1a2b3c4, backend main@5d6e7f8. Verificado: 2026-01-12.
| id | frase | fonte | visibilidade | veredito | notas |
|---|---|---|---|---|---|
| N1 | Acme Tasks planeja seu dia a partir do seu calendário. | frontend/src/planner/plan.ts:31@1a2b3c4; https://docs.example.com/planner | ui | backed | |
| N2 | Tarefas atrasadas são movidas para amanhã à meia-noite. | backend/jobs/rollover.py:12-30@5d6e7f8 | backend | backed | não mostrado na tela |
| screen:board | Board com três tarefas, uma atrasada | frontend/src/pages/board/BoardPage.tsx:14@1a2b3c4 | ui | backed | |
| screen:call | Chamada telefônica com o cliente | (projetado) | mock | mock | marcado no BRIEF |
## Perguntas abertas
1. <pergunta fechada com uma resposta recomendada>
Uma linha por id de linha de lines.tsv, com a frase copiada exatamente (a verificação as compara, então
editar uma linha após a passagem de verdade falha até que você a reverifique). Uma linha por tela, com id
screen:<nome> correspondendo a SOURCES.md. Várias citações vão em uma célula, separadas por ;.
7. Verifique
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/product-truth/scripts/truth_check.py" <video_dir>
Falha em uma linha sem uma entrada, uma frase alterada, um veredito diferente de backed ou approved em uma linha narrada, uma citação cujo papel não está travado, cujo sha não é o travado (o código mudou; reverifique), cujo arquivo não está na exportação, ou cuja linha está além do final do arquivo. Corrija cada falha; não edite a verificação.
Relate ao usuário: quantas linhas e telas estão backed, o que você reescreveu e cortou (com o motivo), o que aguarda aprovação, e as perguntas abertas.