paulmil11/decks

O que decks faz?

O usuário revisa um deck no navegador. Ele digita um comentário embaixo de um slide (ou edita o texto diretamente nele) e depois diz "processar alterações" ou clica em Pergunte ao Claude no deck, que copia um prompt nomeando o arquivo do deck e as etapas sb abaixo; trate esse prompt como "processar alterações" para aquele deck. Você age em cada comentário, responde no próprio slide, verifica seu trabalho e exporta. Mantenha o resumo do chat curto: as respostas nos slides carregam os detalhes.

Onde as coisas estão

• A pasta do aplicativo é o repositório Decks: a pasta na qual este skill é enviado (.claude/skills/decks/ dentro dela) ou, para uma cópia deste skill em ~/.claude/skills/, onde quer que o usuário o tenha clonado. O prompt Pergunte ao Claude a nomeia. Ela contém server.py, a linha de comando sb, o shell do navegador em static/, templates em templates/ e ferramentas headless em tools/. Execute sb a partir dela: ./sb ....
• O servidor: python3 server.py, em http://localhost:8790/ a menos que config.json ou SB_PORT diga o contrário. Se sb disser que o servidor não está acessível, inicie-o (em segundo plano) e tente novamente. sb o encontra em SB_URL ou na porta configurada.
• Os decks ficam na pasta de decks (padrão ~/slide-decks), uma pasta por deck, listados em decks.json lá. ./sb decks os lista com seus endereços.
• Abra um deck em http://localhost:<port>/d/<slug>/<entry>. #s=<slide-id> salta para um slide, e #v=<version>&s=<id> seleciona uma versão.
• O estado salvo fica ao lado de cada deck em .slidebuilder/:
  • state.json: as edições, comentários e ordem dos slides do revisor, espelhados da página. Nunca escreva nele manualmente.
  • review.json: suas respostas, rodadas e badges alterados. Escreva através de sb.
• Toda pasta de deck é um repositório git. PDFs, zips e arquivos PPTX são ignorados.

A página

• Quatro visualizações: Foco (F), Rolagem (S), Classificador (G) e Verificações (C). A tira de filme à esquerda reordena por arrasto.
  • Em Foco e Rolagem, a caixa de comentários fica embaixo de cada slide, com sua resposta abaixo dela. A barra à direita contém as notas do slide e o que mudou.
  • Verificações tem cinco verificações, teclas 1 a 5: o teste de 5 segundos (primeira impressão), o teste de 10 segundos (legibilidade; uma falha deixa um comentário no slide para a próxima rodada), fluxo horizontal (apenas os títulos, editáveis no local), fluxo vertical (o título primeiro, o corpo oculto até ser revelado) e Guias.
  • Comentários podem vir de Verificações: "Teste de cinco segundos: …" e "Teste de dez segundos: …" após um teste cronometrado falho, e "Guias: …" do Pergunte ao Claude para corrigir em Verificações › Guias, nomeando o que o slide quebra. Corrija o slide para que passe, como qualquer comentário.
  • H esconde tudo, exceto os títulos. ? lista todos os atalhos.
• Adicionar um slide (N, "+ Slide" ou o + entre slides) sugere layouts e pode adicionar um que o deck carrega. Seu prompt Copiar fornece o arquivo do deck, a posição e o que o slide deve dizer. Quando um prompt disser "Acabei de adicionar um slide … (LIBRARY['id'])", preencha esse slide; quando disser "adicione um novo slide …", construa-o no arquivo do deck naquela posição.
• Quando o revisor edita um título em Verificações, isso é uma edição inline: integre-a como qualquer outra.
• Ocultar trabalho do cliente (um interruptor no painel, settings.json na pasta de decks) é para gravação ou compartilhamento de tela. Com ele ativado, o servidor omite decks marcados como client e versões listadas em clientVersions. Nunca mostre nomes de clientes na tela quando estiver ativo.

Uma rodada ("processar alterações")

1. cd para a pasta do aplicativo.
2. ./sb comments <deck> lista os comentários a serem tratados, numerados como o deck. Rascunhos são pulados. ./sb edits <deck> mostra as edições de texto inline e movimentos de slides do revisor. Ambos leem do disco, então você não precisa da aba do navegador deles.
3. ./sb status <deck> "Lendo seus 9 comentários" --done 0 --total 9. O revisor vê isso ao vivo na barra superior. Atualize conforme você avança.
4. Para cada comentário:
   • ./sb working <deck> <slide>.
   • Faça a alteração no arquivo do deck.
   • ./sb reply <deck> <slide> done "uma frase simples sobre o que mudou".
   • Se você precisar da decisão do revisor, use question em vez de done. Para algo que você deliberadamente deixou de lado, use skipped e diga o porquê.
   • Um comentário pela metade recebe uma resposta question, não um palpite.
5. Integre as edições inline do revisor no arquivo do deck (a edição deles vence). O Git tem a versão antiga.
6. Verifique cada slide que você tocou:
   • ./sb shot <deck> <ids…>, depois olhe cada imagem.
   • ./sb audit <deck> encontra estouro, sobreposição de rótulos e qualquer coisa que as Guias sinalizem.
   • ./sb comments <deck> não deve mostrar nada novo e não tratado.
7. Finalize:
   • ./sb export <deck> escreve o próximo PDF numerado a partir do arquivo do deck e move os mais antigos para _archive/. Se o navegador ainda contiver edições que não foram integradas, ele avisa: integre-as primeiro. --with-edits exporta exatamente o que o navegador mostra.
   • ./sb round <deck> --summary "…" --changed id="o que mudou" … --export vN.
   • ./sb commit <deck> "Rodada N: …".
   • ./sb idle <deck>.
   • Diga ao usuário onde está o PDF.
8. A página se recarrega sozinha quando o revisor para de digitar. Não recarregue ou limpe a aba deles. No chat: algumas linhas, mais qualquer coisa que precise da decisão deles.

Novos comentários podem chegar enquanto você trabalha. Execute ./sb comments novamente antes de terminar.

O revisor limpa os comentários tratados com "Looks good". Não os adicione a DONE_FB; essa lista é apenas para cópias abertas fora do Decks, como um arquivo enviado para outra pessoa.

O arquivo do deck

• Um arquivo HTML autossuficiente por deck, com três partes que você edita:
  • conteúdo: entradas de LIBRARY ('id': { cat, layout, title, …, notes }), agrupadas em partes por cat (as partes são CATS, nomeadas em CAT_LABELS)
  • figuras: funções FIGS retornando SVG inline
  • versões: PITCHES (cada um um nome e uma lista de ids de slides)
• A versão padrão é a ordem da LIBRARY dentro de cada parte. Para reordenar, mova as entradas da LIBRARY. Uma ordem salva que é igual a um padrão antigo segue o arquivo.
• Aposente um slide com alt:true (ele vai para a prateleira do Classificador) e coloque seu substituto logo antes dele. Não exclua os slides do usuário. Uma versão alternativa de um slide recebe prop:true, replaces:'…' (marcado como "Proposto").
• Uma linha de fonte vai no rodapé via src:'Fonte: …', não em um subtítulo.
• Cores, fonte do título e logotipo: um bloco <style id="deck-theme"> no arquivo do deck e LOGO para o logotipo do deck em img/. Reestilize editando esse bloco, não slides individuais. Sem LOGO, os slides não têm logotipo.
• Grandes mudanças visuais (um novo layout, um redesign): mostre ao usuário um mockup ou duas opções primeiro, depois construa.
• Quando o usuário quiser um arquivo para enviar a alguém, esse é o menu ⋯ Cópia do cliente: a versão na tela apenas com slides (sem notas, comentários, slides do facilitador, outras versões ou edição), imagens dentro, com um botão Apresentar. Cópia editável é o deck inteiro com notas e comentários: nunca envie essa para um cliente.
• Decks saem do painel com ./sb hide <deck> (volta com ./sb show). ./sb delete <deck> --yes move um deck que este aplicativo criou para a Lixeira e apenas cancela o registro de um deck em uma pasta do próprio usuário. Exclua apenas quando o usuário pedir.
• Baixar imagens ou logotipos precisa da aprovação do usuário a cada vez. Diga a eles o nome do arquivo, origem, tamanho e licença, e coloque o crédito no rodapé.

O método

O Decks é construído sobre o método que Paul Millerd ensina na StrategyU. Aplique-o a cada slide que você escrever ou corrigir. Se o skill strategy-slides estiver instalado, ele tem a versão completa: use-o para storylines, títulos e feedback.

Responda primeiro. Comece com a recomendação, depois o contexto, depois as evidências. Construa até a recomendação (situação e complicação, depois as ideias-chave) apenas para um público cético.

Fantasma do deck primeiro. Antes de construir qualquer corpo de slide, escreva todos os títulos de ação em ordem e leia-os como um parágrafo. Se o parágrafo não fizer o argumento, corrija os títulos ou a ordem agora; é o ponto mais barato para corrigir a história. Observe o que cada corpo deve mostrar para provar seu título.

Fluxo vertical: o título é a conclusão, e o corpo a comprova.

• Todo título é um título de ação: uma frase completa que diz o ponto. "A receita do 3º trimestre cresceu 22%, impulsionada pela expansão empresarial", nunca "Receita do 3T".
• Vá além de títulos vagos. "A empresa está melhorando" é o passo um; "A lucratividade aumentou pela primeira vez em 5 anos devido a investimentos na cadeia de suprimentos" é onde chegar.
• Sem caixas de "principal conclusão" ou faixas de resumo na parte inferior. A percepção lidera a página.
• Use verbos simples com seus objetos naturais. Não personifique dados ou force metáforas sobre números. Sem fragmentos com vírgula pivô ("Um modo de pensar, quando o trabalho precisa de dois"). No máximo duas linhas. Leia em voz alta: deve soar como algo que uma pessoa diria a um colega.
• Títulos apenas de contagem são vazios. "Três riscos e como os cobrimos" se torna a descoberta: "A exposição real é o serviço da Costa Oeste, não a capacidade do armazém."
• Capas, divisores de seção e o divisor do apêndice são isentos. O slide de encerramento não: "Aprove até 14 de março e saímos de ambos os contratos de locação antes da renovação", não "Próximos passos".

Fluxo horizontal: apenas os títulos contam a história. Leia-os em ordem (Verificações › Fluxo horizontal). Se eles não fizerem sentido sem os corpos dos slides, corrija os títulos ou a ordem.

Uma ideia por slide. Se um slide precisa de "e também", precisa ser dois slides.

Os testes de cinco e dez segundos são sobre legibilidade. Um slide apresentado transmite seu ponto principal em cinco segundos. Um slide que as pessoas leem pode ser compreendido em dez: um ponto principal, uma hierarquia legível, um gráfico cuja forma se lê sem estudo. Paredes de texto, um número chave enterrado em uma tabela densa e várias ideias não relacionadas em um slide falham todos.

"E daí?" é um teste separado. Três caixas organizadas lendo Inovação, Excelência, Crescimento passam no teste de dez segundos e falham no "e daí?" (síndrome do slide bonito). Cada slide diz ao público o que pensar. Mantenha as duas descobertas separadas ao dar feedback.

Gráficos comprovam o título. Escreva a mensagem antes de desenhar o gráfico. Barras, colunas e linhas cobrem quase tudo; nunca use um gráfico de pizza. O número que importa é a marca mais proeminente, qualquer coisa que o título nomeie (uma recessão, um ponto de inflexão) é marcada no gráfico, e tudo que não apoia o título vai embora. Dados incertos recebem um rótulo "Ilustrativo" e uma nota sobre as suposições.

O resumo executivo é o slide mais importante: a recomendação como seu título e três percepções com uma linha de evidência cada. Use divisores de seção apenas em decks longos (20+ slides) com seções distintas.

Apresentado ou lido. Apresentado: menos de 20 palavras no corpo, uma ideia, visuais grandes. Lido: mais texto é aceitável, com palavras iniciais em negrito, e cada slide se sustenta por conta própria porque será encaminhado.

Dando feedback em um deck. Leia o deck inteiro primeiro. Depois dê, em ordem: a história (os títulos em sequência, o que dizem e o que está faltando ou fora de ordem); os slides que têm um problema, com a correção (escreva o novo título quando o título for o problema); e as três mudanças que mais importam, com o argumento e a ordem antes de fontes e cores. Se o argumento não se sustentar, diga isso primeiro. Verifique cada número de slide antes de citá-lo.

Escrevendo. Verbos ativos, contrações e números em vez de adjetivos. Nunca: mergulhar, panorama, alavancar, utilizar, crucial, fundamental, robusto, perfeito, transformador, sublinhar, adicionalmente, além disso, além do mais. No máximo um travessão por slide.

Regras de estilo de slide

Além do método:

• Sem linhas pequenas, esmaecidas ou itálicas na parte inferior de cartões ou caixas. Incorpore qualquer coisa importante ao item ao qual pertence.
• Sem grades de cartões idênticos. Desenhe o relacionamento: um processo, espectro, escada, gráfico ou mapa.
• Instruções são uma frase simples. Perguntas de reflexão são simples e sobre o próprio trabalho do público.
• Horários da agenda em blocos de 5 minutos.
• Use o próprio material, diagramas e redação do usuário antes de inventar frameworks. Ao cortar, corte primeiro os slides inventados e mantenha construções e pares de configuração/conclusão inteiros.
• Marque o texto que você redigiu nas notas, para que o usuário possa substituí-lo.
• Citações e números vêm apenas de fontes que você abriu na sessão, citados exatamente e atribuídos a quem realmente os disse.
• Tudo passa por Verificações › Guias: a borda protegida, títulos de duas linhas, nada abaixo de 12 px, no máximo quatro tamanhos de texto em um slide. Estas são diretrizes, não regras; corrija o que sb audit listar ou diga por que um slide é uma exceção.

Iniciando um novo deck

O usuário inicia decks a partir do formulário Novo deck no painel, em duas etapas. Etapa 1: um nome, o que estão construindo (uma apresentação, um treinamento, uma palestra, uma proposta ou um deck em branco) e as peças para construir junto com ele. Etapa 2: para quem é, o que sabem e se importam, o ponto principal e comprimento opcional, tipo de público, estrutura, densidade, cores, fonte do título, logotipo e notas. Criar deck cria a pasta, dá a ela seu próprio prefixo de armazenamento, adiciona-a a decks.json, inicia seu histórico git, escreve o briefing em BRIEF.md, copia um prompt para a área de transferência e abre o deck. Quando eles colarem esse prompt:

1. Leia BRIEF.md na pasta do deck e molde o template para ele antes de escrever slides. O template é um ponto de partida, não uma forma fixa:
   • Como será usado. Apresentado: uma ideia por slide, tipo grande, pouco texto; deve passar no teste de 5 segundos. Enviado para ler: cada slide se sustenta por conta própria com um corpo mais completo; deve passar no teste de 10 segundos. Apresentado, depois enviado: slides apresentáveis, com os detalhes nas notas ou em um apêndice.
   • Público e o que eles sabem. Ajuste o vocabulário, os exemplos e o quanto você explica; executivos obtêm a resposta primeiro.
   • Estrutura. Responda primeiro: a recomendação, depois as razões. Situação, complicação, resolução: nessa ordem. Uma história em algumas partes: seções com divisores. Ensine, pratique, reflita: módulos com exercícios e perguntas de reflexão.
   • Densidade. Esparsa, equilibrada ou detalhada, conforme as palavras dizem.
   • Qualquer coisa deixada em branco é sua decisão; a menos que você não possa, então peça.
2. Observe o layout e o tipo LIBRARY que o deck usa. O layout tem seu próprio CATS, CAT_LABELS e a estrutura de 'id': { … }.
3. Escreva os slides em LIBRARY em um rascunho. Para cada slide, comece com um rascunho do título de ação. Leia os títulos em ordem (Verificações › Fluxo horizontal). Se eles não fizerem o argumento, corrija a ordem ou os títulos agora. Uma vez que estejam certos, escreva cada corpo, depois as figuras. Escreva as figuras em SVG inline: FIGS é um dicionário de funções que aceitam largura e altura e produzem SVG inline. SVG tem largura total (width="100%") e altura definida (height="<h>"). Use para rótulos com a fonte do título (font-family="var(--title-font)") se for um título e font-family="var(--body-font)" para o corpo. A cor do traço e do texto vêm de var(--title-color) e var(--body-color) a menos que sejam acentos. Eixos e linhas de grade em var(--grid-color). Dados na cor de acento ou var(--data-color). Dados de sombra em var(--shadow). Números no eixo em var(--axis-color). Setas em var(--accent). Não coloque pontos de dados. Adicione um único rótulo de eixo y ou anotação de conclusão quando necessário.
4. Depois do rascunho, mostre ao usuário a versão fantasma do deck (apenas títulos) e seus slides de rascunho mais ásperos (apenas corpo, sem figuras) como uma pré-visualização. Pergunte por feedback específico: você está no caminho certo? O argumento está configurado corretamente? Eles querem um layout diferente?
5. Quando eles disserem que sim, construa a versão completa e coloque-a em seu primeiro PDF, e eles podem revisar no navegador.