Folheto de Trabalho (Work Brochure)
Após finalizar um trabalho, o usuário deseja duas coisas:
- O resumo normal no chat, exatamente como você o escreveria de qualquer forma (o que mudou, em que pé está, o que não foi feito). Este skill nunca o substitui ou encurta.
- Um folheto: uma página HTML autocontida que percorre o mesmo trabalho visualmente, para que o usuário possa abri-la ao lado do chat e entender a mudança através de diagramas, capturas de tela e código anotado, em vez de parágrafos.
O folheto deve ser fiel ao código. Cada afirmação, número, caminho de arquivo e captura de tela vem do diff real, dos comandos que você executou e do aplicativo que você examinou. Nunca invente um teste que não foi executado ou um resultado que você não viu.
Etapas
1. Escreva o resumo do chat primeiro
Conclua o trabalho normalmente, incluindo seu resumo textual e wrap_up (se o aplicativo tiver um). Em seguida, construa o folheto. Se o usuário pediu apenas o folheto de um trabalho anterior, pule direto para a etapa 2.
Após a abertura de um PR (o hook PostToolUse do plugin, ou um em suas configurações, adiciona um lembrete após gh pr create), construa o folheto para aquele PR com gather.sh --pr <N> na mesma rodada, e coloque o link do folheto em sua mensagem de encerramento. Não edite o corpo do PR para adicioná-lo a menos que o usuário peça. Pule apenas se o PR for uma alteração trivial de uma linha (digitação, aumento de versão).
2. Colete os fatos
Execute o auxiliar a partir da raiz do repositório (ele imprime commits, um diffstat por arquivo agrupado por pasta, alterações não commitadas e informações do PR):
bash <skill-dir>/scripts/gather.sh # este branch vs main + não commitado
bash <skill-dir>/scripts/gather.sh A..B # qualquer intervalo git (ex.: trabalho já mesclado)
bASH <skill-dir>/scripts/gather.sh --pr 51 # um PR do GitHub
Em seguida, leia as partes do diff que importam (git diff <intervalo> -- <caminho>), não o todo. Colete também desta conversa:
- Por quê: o problema ou solicitação nos próprios termos do usuário.
- Decisões: opções que você ponderou e por que escolheu esta.
- Verificação: comandos executados e sua saída real, capturas de tela tiradas, o que você verificou no navegador ou simulador e o que você não pôde verificar.
- Pontos pendentes: acompanhamentos, riscos, algo deixado incompleto.
- Precisa do usuário: qualquer coisa que só eles possam decidir, verificar visualmente ou aprovar.
3. Capture o aplicativo real (quando a mudança é visível)
Se a mudança aparece em uma interface do usuário, o folheto deve mostrar o aplicativo real, não uma descrição dele.
- Depois: tire uma captura de tela do aplicativo em execução na(s) tela(s) alterada(s) com as ferramentas de pré-visualização (
preview_startcom o launch.json do projeto, navegue,computer {action: "screenshot"}), ou o simulador iOSscreenshot. Capture ambas as larguras de desktop e celular quando o layout mudou. - Antes: se a diferença é o ponto principal, faça checkout da revisão base em uma árvore de trabalho temporária no scratchpad (
git worktree add <scratchpad>/before <base>), sirva-a em uma porta diferente, tire uma captura da mesma visualização e remova a árvore de trabalho (git worktree remove). Pule isso quando a mudança for puramente aditiva ou um "antes" não acrescentar nada. - Salve as capturas de tela como arquivos no scratchpad, reduza-os (
sips -Z 1400 -s format jpeg -s formatOptions 78 in.png --out out.jpg) e incorpore-os como URIsdata:. Mantenha toda a página abaixo de ~8 MB. - Para alterações de vídeo/animação, incorpore alguns quadros estáticos (
ffmpeg -ss <t> -i clip.mp4 -frames:v 1 -vf scale=900:-1 still.jpg) ou uma tira de quadros, além dos números medidos. - Alterações não visuais (scripts, dados, backend) recebem diagramas e saída real em vez de capturas de tela.
4. Planeje a história e depois escolha os visuais
Ordene a página como o usuário gostaria que fosse explicada: o resultado primeiro, depois como funciona, depois os detalhes. Escolha os visuais com base no que mudou. Prefira uma imagem sempre que ela explicar mais rápido que texto; mantenha a prosa em legendas curtas e parágrafos de uma a três frases.
| O que mudou | Visual a usar |
|---|---|
| Lógica, pipeline, regra de decisão | Mermaid flowchart do novo fluxo; destaque os nós novos/alterados com classDef changed |
| Solicitações entre partes (UI → API → armazenamento) | Mermaid sequenceDiagram |
| Estrutura (módulos, arquivos, formato de dados) | Mapa de arquivos com barras +/−; Mermaid graph de como as partes se conectam; tabela de campos antes/depois |
| UI | Par de capturas de tela antes/depois; anote com chamadas numeradas sobre a imagem |
| Números (tempos, tamanhos, contagens, desempenho) | Gráfico de barras SVG inline na escala, antes vs depois |
| Estado ou ciclo de vida | Mermaid stateDiagram-v2 |
| Sequência de trabalho (migração, alteração em várias etapas) | Etapas numeradas de passo a passo (apenas quando a ordem é real) |
| Código-chave | Trechos curtos de diff (5–25 linhas) com as linhas importantes marcadas, dentro de <details> para não dominarem |
Procure ter pelo menos três visuais distintos para uma mudança de funcionalidade e pelo menos um para qualquer coisa menor. Os diagramas devem descrever o mecanismo real (nomes reais de funções, nomes de arquivos, valores), não caixas genéricas.
5. Construa a página a partir do modelo
Copie <skill-dir>/template.html e preencha-o. Ele já contém o visual de sketchpad (um tema claro proposital: fundo de papel quadriculado, títulos manuscritos, cartões desenhados a lápis, diagramas à mão livre), o layout e todos os componentes listados acima. Não adicione um modo escuro nem troque o visual a menos que o usuário peça. Regras:
- Mantenha o bloco
<style>e o script de carregamento Mermaid; substitua o conteúdo de exemplo. Exclua seções que não se aplicam em vez de deixá-las enxutas (ex.: sem "Antes → depois" para uma refatoração pura). <title>: o nome da funcionalidade, de duas a quatro palavras (ex.: "Lógica de Retry no Checkout"), não "Resumo do trabalho: …".- Hero: uma frase sobre o resultado, a linha de metadados (branch, link do PR, data) e a faixa de estatísticas (arquivos, linhas +/−, commits, verificações aprovadas). Calcule os números a partir do gather.sh, não estime.
- Precisa da sua contribuição (nota adesiva abaixo do hero): apenas solicitações reais que aguardam o usuário, uma linha cada, informando onde olhar. No máximo três. Exclua toda a nota quando não houver nenhuma; nunca a preencha.
- Por que assim (tabela de decisões): duas a quatro opções que realmente foram ponderadas na sessão, uma marcada como Escolhida, uma compensação de uma linha cada. Não invente alternativas para preencher; se nenhuma escolha real foi feita, exclua a seção.
- Mantenha a página enxuta: estas duas e as seções que se aplicam. Não adicione seções além do modelo.
- Mapa de arquivos: uma linha por arquivo significativo (agrupe arquivos gerados/binários em uma linha), larguras das barras +/− como porcentagem do total do maior arquivo, mais uma linha em português claro sobre por que mudou.
- Trechos de diff: escape
<,>,&. Marque linhas comclass="add",class="del"ouclass="hl"(linha importante não alterada). - Mermaid vai em
<pre class="mermaid">, começando imediatamente após a tag com o bloco de configuração do modelo (---/config:/look: handDrawn/theme: neutral/---) para que renderize à mão livre tanto como arquivo local quanto no claude.ai. Mantenha a linhaclassDef changed fill:#dfe7ff,stroke:#1f4fd1,stroke-width:2pxdo modelo. Escape</>dentro de rótulos como</>, e useclass <ids> changedpara o que este trabalho adicionou ou alterou. Mantenha cada diagrama com cerca de 5–9 nós para caber em uma tela: mescle etapas consecutivas em um nó com uma linha de detalhe<br/>, e divida um fluxo mais longo em dois diagramas. Useflowchart LRpara cadeias curtas,TDpara cadeias ramificadas. - Verificação: liste cada verificação com um chip de aprovado/reprovado/não verificado e sua evidência (trecho de saída ou captura de tela). Itens "Não verificado" são necessários quando existem.
- Escreva de forma clara: frases curtas, nos termos do usuário, sem filler.
Salve como <repo-root>/.claude/work-briefs/<YYYY-MM-DD>-<slug>.html. Mantenha essa pasta fora do git em todos os repositórios sem tocar no .gitignore deles, adicionando-a ao arquivo de exclusão local uma vez:
mkdir -p .claude/work-briefs && x="$(git rev-parse --git-common-dir)/info/exclude" && (grep -qxF '.claude/work-briefs/' "$x" 2>/dev/null || echo '.claude/work-briefs/' >> "$x")
6. Verifique uma vez e depois entregue
- Abra-o uma vez no painel do navegador (
preview_startcomurl: file://<caminho>, ou o servidor estático do projeto) e tire uma captura de tela para confirmar que os diagramas renderizaram e nada transborda. Corrija o que essa única olhada mostrar; não faça loop. - Mostre-o no painel lateral:
SendUserFilecomdisplay: "render". - Publique-o como um Artefato privado (
Artifactpubliqué com o caminho do arquivo,icon: "document", e uma descrição de uma frase) para que sobreviva após a limpeza de uma árvore de trabalho. Esta é a cópia persistente; artefatos começam privados. Se nenhuma ferramenta de Artefato estiver disponível (ex.: sessão de terminal simples), pule isso e forneça o caminho local. - No chat, após seu resumo normal, adicione uma linha com o link do folheto e o caminho do arquivo local.
Atualização: se o usuário solicitar alterações, edite o mesmo arquivo e republique no mesmo caminho para que o link permaneça o mesmo.
Como é um bom folheto
- Alguém que não estava na sessão entende o que mudou e por quê em menos de dois minutos de rolagem.
- A primeira tela responde "o que está diferente agora?" sem precisar rolar.
- Cada diagrama, gráfico e captura de tela é desta mudança.
- O status honesto está visível: o que foi verificado, o que não foi, o que falta.