px-summarize-transcript

O que px-summarize-transcript faz?

Transforma uma transcrição de reunião em um registro com evidências do que foi decidido, quais fatos materiais foram declarados e quem é responsável por cada próximo passo. Cada item cita o falante, o carimbo de data/hora (quando a transcrição possui um) e uma citação literal. Scripts Python fazem o trabalho mecânico: análise, nomeação de arquivos, frontmatter e verificação de citações. Você faz o raciocínio.

Quando Usar

• Um arquivo .vtt, uma transcrição do Teams colada em .txt ou .md, uma transcrição Markdown no formato [Falante] AAAA-MM-DD HH:MM:SS ou linhas Nome: texto precisam de decisões e itens de ação extraídos.
• Alguém pergunta quem disse algo, o que foi acordado ou quem é responsável por um acompanhamento.
• Alguém pergunta o que ainda está em aberto desde a reunião anterior em uma série recorrente.
• Os resultados da reunião devem ser reconciliados com documentos do projeto.

Estrutura do pacote (fixa)

Todos os arquivos ficam na própria pasta da transcrição e compartilham seu nome de arquivo. Apenas o sufixo muda. Você não pode escrevê-los em nenhum outro lugar. Se o usuário pedir outra pasta, explique que o pacote fica com sua transcrição. O file_transcript.py pode mover um pacote inteiro para uma pasta de série, e seus membros sempre se movem juntos.

Arquivo	Função
<stem>.vtt / .txt / .md	Transcrição fonte. Arquivos .md e .txt recebem frontmatter mesclado no local; chaves existentes nunca são alteradas.
<stem>.source.md	Apenas para .vtt: um pequeno arquivo Markdown "sidecar" que guarda o frontmatter do .vtt, porque um arquivo .vtt deve começar com WEBVTT e não pode conter frontmatter.
<stem>.turns.md	Índice de turnos. Criado uma vez; nunca reescrito a menos que você passe --rebuild.
<stem>.summary.md	Relatório. Reexecuções escrevem <stem>.summary.v2.md, .v3 e assim por diante.

Formatos e chaves: formatos de entrada, especificação de frontmatter.

Procedimento

Os scripts estão em ./scripts/ ao lado deste SKILL.md. O terminal inicia no diretório de trabalho do usuário, portanto resolva o caminho absoluto da pasta da skill primeiro (instalações pessoais geralmente são ~/.claude/skills/px-summarize-transcript ou ~/.agents/skills/px-summarize-transcript) e defina-o uma vez por terminal:

$S = "<caminho absoluto para esta skill>\scripts"      # PowerShell

S="<caminho absoluto para esta skill>/scripts"          # bash / zsh

Comandos abaixo usam PowerShell ("$S\build_turns.py"). No bash, escreva "$S/build_turns.py". Os scripts usam apenas a biblioteca padrão (Python 3.10+). Coloque caminhos entre aspas, pois nomes de arquivo frequentemente contêm espaços.

Trabalhe em uma transcrição por vez. Para uma pasta ou "tudo pendente", veja Várias transcrições.

1. Arquivar a transcrição (opcional). Faça isso quando o usuário pedir, ou quando o diretório de trabalho mantém transcrições em pastas de série (por exemplo transcripts/<série>/) e esta ainda não está em uma. --root padrão é ./transcripts.

   python "$S\file_transcript.py" --list --root "<root>"
   python "$S\file_transcript.py" "<transcrição>" --series "<série>" --root "<root>"
   

   Reutilize uma série existente que se encaixe na reunião. Se nenhuma servir, proponha um nome curto em kebab-case e confirme com o usuário antes de criá-la. Em seguida, aja de acordo com status:

   • moved: continue com o novo caminho source.
   • already-filed: a transcrição já está dentro de uma pasta sob a raiz, ou em uma pasta nomeada com a série. Nada foi movido, então continue.
   • duplicate: a mesma transcrição já existe em duplicate_of. Pare e pergunte ao usuário qual cópia processar. Não exclua nenhum arquivo.
   • conflict (código de saída 2): um arquivo diferente com o mesmo nome já está na pasta da série. Pare e pergunte.

2. Construir o índice de turnos.

   python "$S\build_turns.py" "<transcrição>"
   

   Ele detecta o formato, escreve <stem>.turns.md se ainda não existir, marca a fonte (ou sidecar) e imprime JSON. Mantenha turns_path, turns_status, summary_path, has_timestamps, speakers, meeting_date, meeting_date_source, gaps, previous_meeting_summary e transcription.

   • turns_status: created ou kept: continue. kept significa que o índice de turnos existente já corresponde à transcrição, então nada foi reescrito.
   • turns_status: source-changed (código de saída 3): a transcrição foi editada após a criação do índice de turnos, e relatórios existentes citam IDs de turnos antigos. Pare e pergunte ao usuário antes de executar novamente com --rebuild.
   • Erro de formato não suportado (código de saída 2): informe ao usuário quais formatos são suportados e pare.
   • meeting_date é null: escreva "Não informado", a menos que o usuário forneça a data.

3. Leia o índice de turnos completo em grandes blocos até o fim. Nunca extraia de uma leitura parcial.

4. Mapear os falantes. Crie uma linha por rótulo de falante para a tabela de Falantes do relatório: o rótulo, o nome a ser exibido e como você o identificou.

   • Mostre um nome diferente apenas com evidência: a pessoa é chamada pelo nome, se apresenta ou o rótulo é um erro ortográfico óbvio. Registre a evidência.
   • Um rótulo de dispositivo de sala de conferência permanece o nome da sala. Liste quem foi ouvido ou chamado ali, e não atribua suas falas a uma pessoa, a menos que a transcrição torne isso inequívoco.
   • Pessoas mencionadas apenas na linha de cabeçalho Transcription: estiveram presentes, mas não necessariamente falaram.
   • Liste pessoas que são mencionadas mas não falam, com onde foram mencionadas.
   • Resolva primeiros nomes para nomes completos apenas quando for inequívoco.

5. Extrair itens usando estes critérios:

   • Decisão: uma escolha entre opções foi feita ou aceita ("vamos com", "acordado", "faremos", ou uma proposta sem objeção). Status: Acordado, Tentativo ou Proposto.
   • Declaração material: algo que mudaria escopo, design, cronograma, custo ou risco se estivesse errado: fatos sobre sistemas, restrições, dependências, números, datas, compromissos, riscos declarados. Não conversa fiada ou repetições. Mire em 12 ou menos, mesclando declarações relacionadas.
   • Item de ação: uma tarefa futura com um verbo, solicitada ou oferecida ("eu vou", "você pode", "precisamos").
   • Pergunta em aberto: levantada e não resolvida antes da reunião prosseguir.

6. Atribuir responsáveis a cada item de ação. Responsáveis podem ser qualquer pessoa nomeada, incluindo ausentes.

   • Explícito: nomeado e solicitado, não recusou.
   • Voluntário: o falante disse "Eu vou...".
   • Delegado: atribuído a alguém ausente ou silencioso. Marque (não presente) e anote quem delegou.
   • Inferido: decorre de função ou responsabilidade declarada. Escreva o raciocínio.
   • Não atribuído: nenhum dos anteriores. Nunca invente um responsável.

   Registre datas de vencimento apenas se foram ditas.

7. Anexar evidência a cada item:

   • Com carimbos de data/hora: [T042 00:12:31 Falante] "citação literal".
   • Sem carimbos de data/hora (has_timestamps: false): [T042 Falante] "citação literal".
   • Falante é o rótulo exatamente como no índice de turnos, mesmo quando a tabela de Falantes mostra um nome diferente. Use nomes de exibição em todos os outros lugares.
   • Citações têm 25 palavras ou menos, copiadas exatamente, incluindo erros de ASR. Use ... para omissões. Cite vários turnos quando uma decisão se forma ao longo de turnos.

8. Verificar o que foi transferido (apenas quando previous_meeting_summary estiver definido). Leia apenas as tabelas de Itens de ação e Perguntas em aberto desse relatório. Para cada item, decida a partir desta transcrição se está Concluído, Em andamento, Ainda em aberto, Abandonado ou Não mencionado, e cite o turno que mostra isso. Nunca marque um item como Concluído sem que alguém tenha dito isso.

9. Escrever o relatório em summary_path usando o template. Escreva apenas o corpo; não adicione frontmatter. Sempre preencha "Em resumo". Adicione "Para " apenas quando o usuário nomear o leitor, por exemplo "para mim, sou Dana Ruiz". Nunca presuma quem é o leitor.

10. Sinalizar ressalvas de transcrição: prováveis erros de ASR, nomes de falantes que você mapeou por inferência e cada entrada em gaps (conteúdo pode estar faltando). Nunca corrija citações silenciosamente.

11. Verificar citações e corrigir ou descartar cada linha com falha até passar:

    python "$S\verify_quotes.py" "<summary_path>"
    

12. Finalizar o pacote. Derive um título curto do conteúdo da reunião e de 3 a 6 tags de tópico (minúsculas, kebab-case). transcript e meeting-notes são adicionados automaticamente.

    python "$S\finalize_bundle.py" "<transcrição>" --summary "<summary_path>" --title "<título>" --tags "tag-um,tag-dois" --alias "Rótulo na transcrição=Nome de exibição" --mentioned "Nome (contexto)" --meeting-date AAAA-MM-DD
    

    • --alias repete uma vez por rótulo de falante que você mapeou na etapa 4. Os participantes então assumem como padrão os nomes de exibição.
    • --mentioned repete uma vez por pessoa.
    • --attendee "Nome" repete uma vez por pessoa quando você precisa substituir a lista de participantes. --attendees "A, B (sala: C, D)" também funciona, porque vírgulas dentro de () ou [] não dividem.
    • Passe --meeting-date apenas quando meeting_date era null e o usuário forneceu a data.

13. Relatar de volta no chat resumidamente. Não cole as tabelas.

    • Contagens: decisões, declarações, itens de ação, perguntas em aberto e itens transferidos.
    • Os marcadores de "Em resumo".
    • Qualquer coisa que precise de verificação humana: nomes de falantes inferidos, responsáveis inferidos ou não atribuídos, lacunas e ressalvas de ASR.
    • Links para o relatório e o índice de turnos.

Várias transcrições

python "$S\scan.py" "<pasta>" --recursive

Ele lista cada transcrição como new, turns-only, summarized ou not-a-transcript. Mostre ao usuário as pendentes (new e turns-only) e confirme antes de começar. Processe-as uma de cada vez, reunião mais antiga primeiro, para que cada uma possa encontrar a reunião anterior em sua série. Execute o procedimento completo e relate de volta para cada uma antes de iniciar a próxima.

Documentos relacionados do projeto

Se o diretório de trabalho tiver documentos de arquitetura ou planejamento relacionados (incluindo arquivos de resumo de outros pacotes), preencha a tabela opcional "Documentos relacionados do projeto". Observe se cada item confirma, contradiz ou estende o que esses documentos registram.

Verificações de qualidade

• verify_quotes.py passa com 0 falhas.
• A tabela de Falantes tem uma linha para cada rótulo no índice de turnos, e cada mapeamento de nome declara sua evidência.
• Nenhum responsável é nomeado sem evidência explícita, voluntária, delegada ou inferida explicada.
• Decisões marcadas como Acordado mostram um sinal de aceitação, não apenas uma sugestão.
• Opiniões e especulações são rotuladas como tal.
• Responsáveis que não estavam na reunião são marcados como (não presente).
• Cada entrada em gaps aparece sob Ressalvas de transcrição.
• Quando há uma reunião anterior, cada um de seus itens de ação e perguntas em aberto tem uma linha de Transferido.

Pacotes legados

Para alinhar pacotes mais antigos (por exemplo input.txt ao lado de <pasta>.turns.md), execute python "$S\backfill.py" "<root>" para uma simulação, depois --apply. Em seguida, execute finalize_bundle.py por pacote com um título e tags. O backfill nunca regenera um índice de turnos existente, portanto as citações existentes permanecem válidas.