Relatório de Evidências (Relatório de Captura de Tela)

No momento da carga - quando você precisa mostrar um resultado a alguém, mas palavras não são suficientes, e a evidência é a tela real. Se você implementou ou corrigiu uma grande funcionalidade visível na tela, comece o relatório de conclusão aqui, mesmo sem solicitação. Fluxos de navegação entre documentos e telas (sem tela) não são o foco.

Propósito

Criar um documento que responde a uma única pergunta usando capturas de tela reais. O destinatário não lê código nem logs de commit. Tudo o que eles conhecem é a tela; portanto, o peso do documento vem inteiramente do fato de que a tela é o resultado real da execução. É mais rápido e menos contestável mostrar duas fotos lado a lado do mesmo registro em duas telas do que descrever a mesma descoberta em dez marcadores. Se você terminar uma grande funcionalidade e passar para "concluído" sem este relatório, o custo de verificar a tela recai sobre o destinatário.

O resultado é um único HTML. O destinatário pode abri-lo no celular ou imprimi-lo como PDF A4, portanto, o modelo deve se ajustar a telas estreitas e impressão A4. PDF ou Markdown separados não são criados.

Esta skill não tem um sumário fixo. Primeiro, defina a frase que o documento responde e, a partir dela, os eixos de comparação e a estrutura das seções.

Pergunta	Eixo de Comparação	O que o Documento Faz
O que mudou	Código anterior <-> Código atual	Coloca duas telas lado a lado para provar a melhoria
Foi feito conforme o planejado? O que falta?	Especificação, documento <-> Tela atual	Atribui um status a cada item e destaca apenas as discrepâncias
Está de acordo com nossos princípios?	Princípios, checklist <-> Produto atual	Agrupa as descobertas por causa e captura as que podem ser mostradas na tela como evidência
O que muda se a condição mudar?	Estado A <-> Estado B	Altera flags, datas, permissões e captura os resultados
Qual é o estado atual?	Nenhum eixo	Mostra toda a tela atual sozinha
O que precisa ser decidido?	Opção <-> Opção	Para cada item, combina a tela atual, as opções e a entrada necessária

É comum que mais de um eixo se misture. Ao comparar com a especificação, pode surgir "algo que não estava no planejamento, mas já existe". Isso é um item de eixo diferente e merece uma seção separada. Se a pergunta for difusa, o documento também será. Se não couber em uma frase, divida o documento em dois.

Princípios Fundamentais

A tela é o resultado real da execução, não uma reconstituição. Criar algo "como deveria ser" baseado em memória é quase sempre errado. A tela anterior pode ter elementos agora removidos, ou o problema pode ser menor ou maior do que o lembrado. "Sob esta condição, deve aparecer assim" também está errado. Ativar a flag mostra uma tela diferente do esperado. Portanto, crie o estado a ser mostrado e então capture. Só assim você pode escrever no documento "Este é o resultado real, não uma simulação", e essa única frase determina a credibilidade de todo o documento. -> Etapa 3
Coloque valores ao lado da foto. A foto diz "assim parece". Colocar os valores armazenados e os valores na tela (atributos data-*, texto de acessibilidade) lado a lado explica "por que parece assim". -> Etapa 3
Desenhe as marcações dentro da tela. Inserir coordenadas aproximadas quase sempre desloca uma coluna ou linha. Se for uma tela de navegador, encontre o elemento pelo texto ou seletor, desenhe uma borda e um número no local e capture. -> Etapa 4
A explicação não deve cobrir o que está sendo explicado. Colocar rótulos de destaque diretamente sobre a tela quase sempre cobre algo. Títulos, rótulos de campos de entrada, valores na coluna ao lado ficam ocultos. Coloque apenas números na imagem e a descrição na legenda. Um pequeno badge numérico causa menos perda, independentemente de onde for colocado. -> Etapa 4
O que você criou, você deve ver com seus próprios olhos. A ferramenta retornar sucesso significa apenas que o arquivo foi escrito. Você precisa abrir para ver se a borda foi para o elemento errado, se o badge cobriu o conteúdo, se o cabeçalho da tabela se repetiu na emenda, ou se a imagem está quebrada no link fornecido. -> Etapas 5 e 6
Separe o que foi capturado do que não foi. Itens confirmados por código, mas sem casos nos dados para mostrar na tela, são marcados separadamente como "(evidência de código)". Misturar os dois coloca em dúvida o peso das evidências capturadas. -> Etapas 1 e 3

Políticas

Política	Quando se Aplica	Conteúdo
Dados e configurações são somente leitura; pergunte antes de alterar	Etapa 3	Consultas para encontrar casos são livres. Alterar o banco de desenvolvimento para criar um caso só é permitido após confirmação do usuário, e o valor alterado deve ser registrado e revertido. O banco de produção nunca é alvo
Registre o que foi alterado durante a captura no documento e no relatório	Etapa 3 · Etapa 6	Vestígios deixados pelo processo de captura, como criação de sessão de login, consentimento de login externo, alterações no banco de desenvolvimento
Entregue em um formato que o destinatário possa abrir	Etapa 6	Caminhos locais não abrem no dispositivo do destinatário. Envie o arquivo `report.html` ou crie um link e, se for link, verifique se ele realmente abre antes de enviar
Obtenha confirmação para enviar para fora	Etapa 6	Para Slack, e-mail, entrega ao cliente, pergunte primeiro se deve deixar como rascunho ou enviar diretamente

Pré-requisitos

Pré-requisito	Verificação	Se não estiver presente
O trabalho aparece na tela	A mudança aparece na tela que o usuário vê?	Trabalhos que alteram apenas backend ou scripts não são alvo. Relate por escrito
O produto a ser capturado está em execução	O servidor de desenvolvimento local ou endereço de staging responde?	Siga a documentação do repositório para iniciá-lo. Para código anterior, veja eixos §eixo temporal
Ferramenta de navegador disponível	`node scripts/shot.mjs` roda com Playwright? Outras ferramentas também funcionam se puderem executar JavaScript na página	Instalação do Playwright e instruções para outras ferramentas estão em captura §manipulação do navegador
Possibilidade de fazer login	A tela requer login? Você tem uma conta?	captura §criando estado de login
Python Pillow	`python3 -c "import PIL"`	Sem ele, não é possível juntar ou recortar imagens

Procedimento

0. Pergunta e eixo     LEIA <- variants/axes - Cada eixo tem preparações diferentes (reverter código, alterar dados, ler documentos, encontrar casos). Apenas as seções do eixo escolhido
1. Itens e veredito   (Se for eixo de inspeção, axes §eixo de inspeção 1~2 criarão os itens)
2. Estrutura          LEIA <- steps/20-document - Critérios para agrupar itens em seções, vocabulário de veredito, resumo, lugar de figuras e tabelas
3. Captura            LEIA <- steps/30-capture - Problemas com login, eventos sintéticos, telas longas, leitura de valores na tela
4. Marcação           LEIA <- steps/30-capture §marcação desenhada dentro da tela - Inserir coordenadas desloca uma coluna
5. Verificação da imagem   (Nenhum documento para abrir. Lista de verificação dentro da Etapa 5)
6. Saída              LEIA <- steps/60-output - Quebrar o modelo quebra a visualização em celular e a impressão; violar as regras do bloco de decisão faz com que o pacote copiado seja cortado

Etapa 0. Pergunta e Eixo

Escreva em uma frase. Deve incluir o destinatário e o propósito, como "Explicar as mudanças desta semana ao cliente" ou "Alinhar com o gerente de produto o que resta em relação à especificação". Se o propósito for diferente, mesmo com a mesma tela, o que será enfatizado muda. Em seguida, escolha o eixo na tabela de propósitos e leia a seção correspondente em axes.

Ao final, você deve ter uma frase de pergunta, um eixo e um destinatário definidos.

Etapa 1. Itens e Veredito

Não comece pela captura. Liste os itens a serem abordados neste documento e atribua a cada um um código de referência e um veredito. Esta lista é a espinha dorsal do documento; ela também determina quais telas capturar e onde marcar.

Os códigos de referência têm prefixos diferentes para itens de naturezas distintas, pois o interesse do destinatário varia.

Tarefas solicitadas: R-1, R-2 ... (o destinatário quer saber se foi feito)
Descobertas feitas e corrigidas durante o trabalho: A-1, A-2 ... (o destinatário quer saber por que foi mexido)
Discrepâncias em relação à especificação: G-1, G-2 ... (o destinatário quer saber o que será feito)
Descobertas de inspeção: seguem o número do grupo 1-1, 1-2 ... (itens com a mesma causa são agrupados)

O vocabulário de veredito deve ser o mesmo em todo o documento (exemplos em document §vocabulário de veredito). Conte os vereditos e coloque o total na primeira página. Uma linha "35 implementados, 3 necessitam decisão, 1 defeito" substitui todo o documento. Contar também revela lacunas na lista.

É fácil esquecer correções feitas durante o trabalho; use git log para preencher a lista. No caso de comparação com especificação, percorra o documento original linha por linha. Marque também se cada item pode ser mostrado na tela (se o caso existe nos dados). -> Princípio Fundamental 6

Ao final, cada item deve ter código, veredito, tela a capturar ou "(evidência de código)".

Etapa 2. Estrutura

As seções não são escolhidas de um sumário; elas surgem ao agrupar os itens. O critério de agrupamento é um dos quatro:

Por tela - quando vários itens estão concentrados em uma tela. Padrão para relatórios de melhoria
Por veredito - quando os vereditos divergem. Padrão para relatórios de comparação; o destinatário vê primeiro apenas "o que precisa ser decidido"
Por causa - quando há muitas descobertas espalhadas por várias telas. Padrão para relatórios de inspeção
Por item - quando cada item é uma decisão independente. Padrão para documentos de tomada de decisão

Em qualquer caso, coloque um resumo que conte toda a história em uma página no início e, em seguida, os detalhes. Presuma que o destinatário vai ler de cima para baixo e pode parar a qualquer momento. O número de seções depende do que está sendo mostrado. Não as force; não crie seções vazias. Métodos específicos para estruturar e exemplos reais estão em document.

Etapa 3. Captura

A preparação varia de acordo com o eixo (axes). Aqui estão apenas as regras comuns.

Capture pares a serem comparados com a mesma viewport, mesma posição de rolagem e mesmo intervalo. Assim, as duas imagens se alinham em nível de pixel, permitindo visualização com slider e diferença (60-output §visualização lado a lado)
Use os mesmos dados para telas que estão sendo comparadas. Dados diferentes invalidam a comparação. Para mostrar que um mesmo fato aparece de forma diferente em telas diferentes, capture todas com o mesmo registro
Verifique com uma consulta antes da captura se os dados necessários para a funcionalidade realmente existem. Capturar uma tela vazia e descobrir depois exige reconstruir a pilha
Verifique o estado de login antes de capturar. Um erro comum é capturar um elemento que aparece apenas com login no estado de logout e escrever "não existe". Antes de declarar algo como ausente, diferencie se realmente não existe ou se não está visível na sessão atual
Opere na mesma ordem. Ter a lista de capturas em um único arquivo permite executar apenas esse arquivo ao recapturar
Defina a viewport com folga. Se a parte inferior da tela for cortada, você terá que recapturar
Leia os valores armazenados e os valores na tela juntos. -> Princípio Fundamental 2
Registre como chegou àquela tela. Para refazer o caminho depois, você precisará navegar novamente. Anotar durante a captura é de graça (document §localização e profundidade da tela)

Para pontos de dificuldade comuns na manipulação, veja capture.

Etapa 4. Marcação

Se for uma tela de navegador, use scripts/shot.mjs para desenhar bordas e números na tela no momento da captura (-> capture §marcação desenhada dentro da tela). Para telas longas, capture em partes e junte com scripts/stitch.py; para partes fora do foco, como uma barra lateral, recorte com o mesmo script. Para telas que não são de navegador, use grid_overlay.py para ler as coordenadas e annotate.py para desenhar.

A borda deve envolver apenas o elemento a ser destacado. Uma borda muito ampla torna o foco difuso
A cor deve ser consistente com o veredito em todo o documento. Ao folhear o documento, a cor revela a natureza. Vermelho para estado anterior e problema, verde para estado melhorado; em relatórios de comparação, vermelho para ausente, verde para presente, laranja para necessita decisão
As marcações em duas telas sendo comparadas devem ser feitas separadamente. O comprimento do texto pode diferir, deslocando sutilmente o layout
Reúna todas as capturas e marcações em um único arquivo. Corrigir uma marcação exigirá recriar tudo, e ao recapturar a tela, basta executar esse arquivo

Etapa 5. Verificação da Imagem

Abra todas as imagens com uma ferramenta de leitura. Verifique:

A linha de resultado da marcação não contém NOT FOUND?
A borda envolve exatamente o elemento a ser destacado? Ela não está pegando outra ocorrência do mesmo texto (por exemplo, o mesmo nome de coluna em outra tabela)?
O badge numérico não está cobrindo texto ou células de barras?
Cabeçalhos ou sumários não estão se repetindo na emenda?
O título não está parcialmente cortado na parte superior recortada? As proporções das duas imagens lado a lado não estão excessivamente diferentes?
O que foi escrito como "ausente" realmente não está na tela? Se estiver oculto devido ao estado de login ou condição, o veredito deve ser invertido
A legenda corresponde ao que a foto mostra? Na largura, você não escreveu "repetido três vezes" para uma coluna oculta?

Corrija as discrepâncias e verifique novamente. Acertar de primeira é raro.

Etapa 6. HTML e Entrega

Copie assets/web-report.html para index.html na pasta do relatório e preencha. O esqueleto e o formato do cartão estão em 60-output §esqueleto.
Se o destinatário precisar decidir algo, coloque um bloco de decisão logo abaixo do cartão de evidência. Pressionar Copiar na barra agrupa o que foi decidido em Markdown para colar na conversa (60-output §obtendo decisões).
Abra os três modos de visualização: tela larga, largura de 390px e todas as páginas de impressão extraídas por scripts/check_print.sh (60-output §tela e impressão).
Use inline-images.py para criar um único arquivo report.html. Envie o arquivo diretamente ou exporte um link. Abra-o da mesma forma que o destinatário abriria para verificar (60-output §entrega).

Não modifique o <style> do modelo para cada relatório. Fixar a largura em px ou colocar uma tabela fora de .tw quebrará a visualização em celular. -> Princípio Fundamental 5

Ao final, report.html não deve quebrar nos três modos de visualização, deve abrir da mesma forma que o destinatário abrirá, e o envio deve aguardar confirmação do usuário.

Problemas Frequentes

Sintoma	Causa e Ação
O servidor de desenvolvimento morre imediatamente	`next dev` lê stdin. Fornecer `< /dev/null` envia EOF e encerra normalmente. Use `tail -f /dev/null
Popover ou dropdown não abre	Radix e outros não respondem a eventos sintéticos. Use o clique real da ferramenta de automação em vez de `dispatchEvent`
A captura de página inteira repete a mesma tela ou cabeçalhos fixos se sobrepõem	A captura de página inteira da ferramenta não consegue rolar a janela ou o contêiner interno. Use `full` do `shot.mjs` para capturar em partes e juntar
O sumário se repete na imagem costurada	Elementos fixos permaneceram. Capture ou recorte apenas a seção em foco
Tabela ou imagem fica fora da tela no celular	A tabela não foi envolvida em `.tw` ou um `style` inline fixou a largura em px. Use apenas as classes do modelo
A marcação aponta para a tabela errada	O mesmo texto aparece várias vezes na tela. Mude o `nth` ou use `exact`; estreite com o seletor
A aba errada é capturada	Outra sessão está compartilhando o daemon do navegador. Isole as sessões
Escrevi que uma funcionalidade existente está ausente	Capturei no estado de logout ou com condição incorreta. Verifique o login e a condição antes de emitir o veredito
Algumas imagens estão vazias ao abrir pelo link	O servidor simples perdeu requisições simultâneas. Use `inline-images.py` para criar um único arquivo
A imagem aparece pequena dentro do quadro	Está sendo reduzida devido a uma restrição de altura. Imagens longas na vertical podem ser dispostas em duas colunas para ficarem maiores
A mudança parece muito sutil	O alvo de comparação foi mal escolhido. Mostrar a tela de edição onde o valor é realmente editado é melhor do que mostrar apenas uma coluna renomeada em uma tela de lista
A tabela está densa e difícil de ler	Transforme em uma lista de itens com o rótulo à esquerda e o conteúdo à direita. Se houver grupos, coloque o rótulo do grupo apenas uma vez na linha esquerda
O documento fica cada vez mais longo	Ao criar uma nova seção, remova a descrição existente que continha aquele conteúdo

Mecanismos Comuns

Script	O que faz	Saída
`scripts/shot.mjs`	Abre telas com Playwright conforme a lista de capturas, desenha marcações e captura. Telas longas são capturadas em partes	PNGs na pasta de saída, uma linha de resultado de marcação cada
`scripts/mark.js`	Encontra elementos na página por texto ou seletor e desenha bordas e números. Usado por `shot.mjs`; em outras ferramentas de navegador, pode ser injetado com eval	Uma linha de resultado de marcação cada
`scripts/stitch.py`	Junta partes capturadas e recorta por coordenadas nomeadas	PNGs na pasta de saída, uma linha de tamanho cada
`scripts/inline-images.py`	Incorpora imagens e scripts de caminho relativo em um único arquivo HTML	`report.html`, contagem de arquivos e tamanhos incluídos
`assets/decisions.js`	Salva blocos de decisão e, com o botão Copiar na barra inferior, agrupa o que foi decidido em Markdown para copiar	Barra fixa, localStorage
`assets/compare.js`	Adiciona modos lado a lado, slider e diferença sobre `.pair[data-compare]`. O modo é um estado global da página; o padrão é slider. Se as duas imagens tiverem tamanhos de pixel diferentes, a sobreposição é desativada	Barra de comparação, taxa de diferença
`assets/report-nav.js`	Constrói o sumário à esquerda a partir de `h2`/`h3`, mostrando volume (seções, fotos, decisões, tempo de leitura), seções lidas, decisões restantes e posição atual. Ao reabrir, continua de onde parou	Sumário à esquerda (gaveta em telas estreitas), localStorage
`scripts/serve-tailscale.sh`	Em ambientes com Tailscale, exporta a pasta para um endereço HTTPS dentro da tailnet e verifica a resposta (opcional)	URL, PID, comando para desmontar
`scripts/check_print.sh`	Gera um PDF A4 de verificação na pasta temporária, mesmo caminho da impressão do navegador	Caminho do PDF, número de páginas, PNG por página
`scripts/grid_overlay.py` · `scripts/annotate.py`	Para imagens fora do navegador, sobrepõe uma grade de coordenadas e desenha caixas e legendas	Imagem anotada

Instruções de uso e avisos estão nos comentários do cabeçalho de cada script.

Saída

Uma pasta de relatório (<data>-<tema>/): index.html para edição, imagens em images/ (originais em images/raw/), arquivo de lista de capturas e coordenadas de recorte, report.html para entrega (imagens incorporadas em um único arquivo). Ao entregar, informe o link, o que foi alterado durante a captura e os itens que não puderam ser mostrados na tela.

Posição no Ecossistema da Skill

Ferramenta de navegador - Esta skill trata de como capturar e inserir no documento com a ferramenta escolhida. Se houver regras específicas do ambiente para escolher a ferramenta e isolar sessões, siga-as
Skill de documento - Relatórios, propostas e slides sem tela são de responsabilidade de uma skill de documento geral, não desta
Revisão de texto - Se houver critérios no ambiente para refinar as frases do relatório e a composição da tela, use-os. No eixo de inspeção, também pode servir como fonte dos princípios

kimjisub/agent-skills

O que é agent-skills?

Perguntar na sua IA favorita

Documentação