Communitygithub.com

work-brochure

Guia o usuário pelo trabalho concluído como um folheto visual em HTML (fluxogramas, capturas de tela do antes/depois do aplicativo real, decisões, mapas de arquivos, trechos de diff, evidências de verificação), além do resumo de texto normal no chat. Funciona em qualquer repositório.

O que é work-brochure?

O skill **Work Brochure** transforma o resumo de uma tarefa concluída em um folheto visual HTML independente, complementando o resumo textual que o agente já fornece no chat. Ele é acionado automaticamente quando um Pull Request é aberto (por hook), quando uma funcionalidade, correção ou item de trabalho é finalizado, ou quando o usuário solicita explicitamente com comandos como '/work-brochure'. O skill executa scripts para coletar informações do diff, commits e status do PR, captura screenshots reais do aplicativo (antes e depois, quando aplicável), e gera diagramas Mermaid (fluxogramas, diagramas de sequência, gráficos de barras SVG) para ilustrar a lógica, estrutura e métricas da mudança. O resultado é salvo em '.claude/work-briefs/', exibido no painel lateral e publicado como artefato privado. Ele não substitui o resumo normal do chat nem deve ser usado para ajustes triviais de uma linha ou para perguntas e respostas puras. O objetivo é que qualquer pessoa que não participou da sessão entenda o que mudou e por quê em menos de dois minutos de rolagem.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lincolncrooks/work-brochure/tree/HEAD/skills/work-brochure

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Folheto de Trabalho (Work Brochure)

Após finalizar um trabalho, o usuário deseja duas coisas:

  1. 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.
  2. 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_start com o launch.json do projeto, navegue, computer {action: "screenshot"}), ou o simulador iOS screenshot. 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 URIs data:. 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 mudouVisual a usar
Lógica, pipeline, regra de decisãoMermaid 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
UIPar 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 vidaMermaid 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-chaveTrechos 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 com class="add", class="del" ou class="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 linha classDef changed fill:#dfe7ff,stroke:#1f4fd1,stroke-width:2px do modelo. Escape </> dentro de rótulos como &lt;/&gt;, e use class <ids> changed para 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. Use flowchart LR para cadeias curtas, TD para 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

  1. Abra-o uma vez no painel do navegador (preview_start com url: 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.
  2. Mostre-o no painel lateral: SendUserFile com display: "render".
  3. Publique-o como um Artefato privado (Artifact publiqué 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.
  4. 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.

Habilidades Relacionadas