sheets-to-playbook

Transforma uma pasta de fotos de folhas de exercício de papel (workshop/sessão comunitária), fotos de cartões de compromisso e notas de voz opcionais num rascunho de site playbook, verifica cada linha contra as fotos e publica-o.

O que é sheets-to-playbook?

Esta skill automatiza a transformação de fotos de exercícios em papel (de workshops ou sessões comunitárias), juntamente com cartões de compromisso e notas de voz, num site playbook rascunho. Ela garante que cada linha do site tenha uma origem rastreável (foto ou nota de voz), usando o verificador `ingest.py verify` para manter a integridade. A skill suporta plataformas como Claude Code e segue um fluxo de trabalho de 6 etapas: preparação, etiquetagem e verificação de cobertura, transcrição paralela (com agentes para cada tabela), escrita do playbook (seguindo `RAW_FORMAT.md`), verificação e correção, e publicação final. É ideal para organizadores que precisam de um playbook fiel às anotações originais, sem inventar conteúdo, e inclui ferramentas para revisão manual de leituras incertas.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Chris-Keene/sheets-to-playbook/tree/HEAD/.claude/skills/sheets-to-playbook

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

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

Documentação

Sheets to playbook

Repositório: a pasta que contém ingest/ingest.py (o projeto atual, se o Claude Code foi aberto no clone). Todos os caminhos abaixo são relativos a ele. Leia ingest/RAW_FORMAT.md antes da etapa 3: contém o formato de transcrição e as regras para escrever o playbook.

O objetivo é rapidez no dia sem inventar nada. Cada linha no site deve ter origem numa foto ou nota de voz; ingest.py verify impõe isso.

Diga ao utilizador o que está a fazer em cada etapa, numa ou duas linhas. As durações abaixo são guias aproximados para cerca de uma dúzia de mesas.

Antes do evento, playbook.config.json deve nomear os organizadores e dar o endereço web do playbook (o código QR do cartão de compromisso aponta para lá). Se ainda tiver os padrões neutros, diga-o, mas continue: as definições só mudam nomes e cores, nunca o conteúdo. --config <ficheiro> em verify, draft e publish escolhe um ficheiro de configuração diferente.

1. Preparar (1 a 2 minutos)

python3 ingest/ingest.py prepare "<pasta>"
python3 ingest/ingest.py transcribe      # apenas se a pasta tiver notas de voz; execute em segundo plano

prepare cria uma nova execução em runs/ (e aponta runs/latest para ela): fotos rodadas para a posição vertical, HEIC convertido, uma pontuação de nitidez por foto, mosaicos 2×2 para leitura aproximada, folhas de contacto em contact/ e notas de voz convertidas para WAV 16 kHz. transcribe usa Whisper local (small.en, offline após o primeiro download) e adivinha a mesa de cada nota a partir de "Mesa sete…" no início.

Um segundo lote (mais fotos, ou os cartões, depois da primeira metade estar em andamento): python3 ingest/ingest.py prepare "<pasta>" --into <exec> adiciona-os à mesma execução. Novos IDs continuam a partir do último (P022…), as etiquetas e ficheiros originais são mantidos, e ficheiros já na execução são ignorados. Em seguida, etiquete apenas os novos IDs.

2. Etiquetar e verificar cobertura (cerca de 5 minutos; faça isto primeiro, é crítico em termos de tempo)

Veja cada folha de contacto (contact/folha-*.jpg) e, onde uma miniatura não estiver clara, a foto em view/. Escreva labels.json na pasta da execução:

{"photos": {"P001": {"table": 7, "sheet": "S2"}, "P014": {"kind": "stubs"}, "P020": {"kind": "other", "note": "foto da sala"}},
 "audio":  {"A01": {"table": 7, "by": "fala"}}}
  • Cada folha tem um código impresso no canto inferior (S1, S2, S3, SS) e cabeçalhos impressos; o número da mesa é escrito à mão pelo líder da mesa, no círculo superior direito e ao lado do código (S2 · Mesa 7). Os cabeçalhos padrão do kit: S1 "Onde é que o apoio fica preso?", S2 "O que ajudou, ou não?", S3 "O que as pessoas poderiam tentar agora, e como é que se fixa?", SS folha lateral "Ouviu algo bom? Escreva aqui." (Citações · Perguntas · Recursos). Se os organizadores mudaram as perguntas, guie-se pelo código impresso. Quando o círculo e o canto discordam, a cor da caneta e o conteúdo resolvem: verifique as outras folhas da mesa.
  • Mantenha quaisquer etiquetas de áudio que transcribe já tenha preenchido, depois de verificá-las com a primeira linha da transcrição.
  • Duas folhas diferentes com o mesmo código e número de mesa (status lista qualquer folha com mais de uma foto: verifique essas): se os países e conteúdo se sobrepõem, é uma mesa que usou duas cópias; etiquete ambas com o número e o leitor transcreve ambas. Se são claramente duas mesas, atribua à segunda um número extra a partir de 91, adicione "note": "escreveu 22; segunda mesa" e informe o utilizador. Qualquer mesa pode ser "a segunda": escolha uma e descreva ambas nas notas (setor, cor da caneta) para que a revisão as distinga.
  • Um close-up sem número de mesa visível (apenas a caixa de contagem, por exemplo): etiquete-o com a folha que corresponde e adicione "note": "mesa inferida de <o que correspondeu>".
  • Duas folhas numa foto (coladas lado a lado): etiquete como "sheet": ["S2", "S3"] para que status conte para ambas, e diga-o numa note para que o leitor saiba que metade é qual.
  • prepare não consegue rodar uma foto que está ao contrário no quadro (não há sinalizador de rotação para ler). Os leitores lidam com isso, mas diga-o numa note. Fotos de cartões pontuam menos em nitidez que folhas (cartão liso, caneta fina), por isso verifique um cartão BORRADO? em view/ antes de pedir uma nova foto.

Depois execute python3 ingest/ingest.py status (adicione --tables <n> se não houver 12 mesas) e informe o utilizador imediatamente sobre qualquer folha FALTANTE ou BORRADA. As folhas de contacto também marcam BAIXA-RESOLUÇÃO (reenviadas por uma app de mensagens: ok se a escrita for grande) e ESCURA (geralmente lê-se bem): mencione-as, mas não são refotos. Idealmente, esta verificação acontece enquanto as folhas ainda estão na parede e podem ser fotografadas novamente.

3. Transcrever cada mesa (paralelo, cerca de 5 a 10 minutos)

Crie um subagente por mesa (ferramenta Agent, general-purpose, em segundo plano, tudo numa mensagem), mais um para os cartões de compromisso se houver. Não rebaixe o modelo: a precisão da caligrafia é onde importa. Cada prompt deve ser autónomo e incluir:

  • O caminho absoluto do repositório, a pasta da execução, o número da mesa, os IDs das suas fotos (view/<id>.jpg e os mosaicos listados em manifest.json) e o caminho da transcrição de voz, se houver.
  • "Leia ingest/RAW_FORMAT.md, etapa 1, e siga-o exatamente. Escreva raw/T<nn>.json na pasta da execução, depois execute python3 ingest/ingest.py verify --run <exec> e corrija qualquer erro que denuncie sobre o seu ficheiro. Responda com um resumo curto: itens por folha, cada entrada unclear e cada palavra rasurada que omitiu."
  • Para cartões: escreva raw/commitments.json conforme descrito no final da etapa 1, incluindo o Nome e Organização opcionais do cartão exatamente como escritos, e seguindo as regras de cartões (cartões não rasgados, assinaturas, um cartão em duas fotos).

Enquanto eles decorrem, leia as transcrições de voz (se houver) para conhecer a sala antes de escrever.

4. Escrever o playbook (cerca de 10 a 15 minutos)

Siga RAW_FORMAT.md etapa 2. Escreva <exec>/session.json com meta.status: "draft". Comece meta a partir de examples/session-template.json e preencha os detalhes do próprio evento (nome do evento, data, local) a partir do que o utilizador lhe disser; defina people para o número real de participantes, se o souberem. Nunca adivinhe estes: deixe um campo como está no modelo e liste-o para o utilizador.

5. Verificar, corrigir, construir o pacote de revisão

python3 ingest/ingest.py verify --links
python3 ingest/ingest.py draft            # <exec>/playbook-draft.html: caixas tracejadas = lacunas, etiquetas = fontes
python3 ingest/ingest.py review           # <exec>/review.html: cada item ao lado das suas fotos

Corrija cada erro (uma linha não rastreável, uma citação que se desviou, um nome deixado) e reexecute até verify passar. Avisos são para a revisão humana: reporte-os, não os encubra.

Depois dê ao utilizador o resumo da revisão: os desafios e que mesas se fundiram, cada leitura unclear com o ID da foto, cada palavra rasurada que um leitor omitiu, itens brutos não usados, problemas de links e qualquer coisa sobre a qual não teve a certeza como agrupar. review.html mostra as notas de cada leitor e a contagem "Quem está nesta mesa?" debaixo de cada mesa. Abra review.html e playbook-draft.html para eles.

Muitas palavras incertas? A aplicação de revisão é mais rápida do que ler review.html de cima a baixo: python3 tools/review/make_review.py --run <exec> constrói <exec>/review/index.html, um cartão por leitura incerta com um close-up da caligrafia. O utilizador confirma ou corrige cada uma, guarda um ficheiro de decisões, e python3 tools/review/apply_review.py --run <exec> <decisoes.json> escreve as leituras de volta nos ficheiros brutos e em session.json. Reexecute verify e draft depois. Perguntas que não são uma palavra incerta (um visto que pode ser um rasuramento, se deve fundir duas mesas, se deve nomear um recurso) vão para <exec>/review/extra.json como verificações e decisões antes de construir a aplicação; apply_review.py lista as respostas em <exec>/review/to-action.md para agir. Veja tools/review/README.md.

6. Publicar (após um humano ter verificado o rascunho)

Aplique as correções dos revisores a session.json, defina meta.status para "final", depois:

python3 ingest/ingest.py publish --links  # recusa se algo não for rastreável ou uma secção estiver vazia

Isto escreve data/session.json e playbook/index.html. A pasta playbook/ é um site estático: implantá-lo em qualquer lugar é um passo separado, por isso pergunte primeiro. Cada link na página é tratado em script, por isso também funciona se for aberto diretamente do disco.

Nunca

  • Adicione conteúdo de conhecimento geral, mesmo contexto "útil". Vazio é melhor que inventado.
  • Adivinhe uma palavra silenciosamente: use [?palavra] ou [ilegível] e liste-o.
  • Coloque o nome de uma pessoa ou empregador na página publicada, exceto o próprio nome e organização do compromisso que a pessoa escreveu no seu cartão (verify verifica esses contra o cartão).
  • Publique sem verify passar e um humano ter lido o rascunho.

Depois

As fotos e notas de voz podem conter nomes e rostos. Assim que o playbook estiver final, lembre o utilizador de apagar runs/*/audio, as fotos e notas de voz originais, e qualquer outra coisa que os organizadores tenham concordado em não manter.

Habilidades Relacionadas