create-doc — Criar documento de estrutura para slides

Create-doc — Criar estrutura para o skill de criação de slides

Lê os registros da pesquisa (md de execução, CSV de resultados, figuras, código) e escreve um documento de estrutura em Markdown, onde cada ## define o que dizer, com que layout, o que colocar e o que falar.

O destinatário é o skill progress-report-deck (no mesmo plugin research-slides, na pasta vizinha ${CLAUDE_SKILL_DIR}/../progress-report-deck/). A saída deste skill é feita para que progress-report-deck leia cada ## como um slide e preencha um template. Antes de começar, leia ${CLAUDE_SKILL_DIR}/../progress-report-deck/SKILL.md e verifique se não há conflitos com as regras abaixo (se as regras de lá mudaram, adapte-se a elas). Se não encontrar, siga este acordo.

Se existir o perfil do usuário ~/.claude/yapi-skills/profile.md (nome, área de pesquisa, público-alvo, regras próprias), leia-o primeiro. Regras próprias (como esquema de cores, tamanho mínimo de fonte) têm prioridade sobre o acordo abaixo e devem ser copiadas para a seção "Sobre este documento" da estrutura.

O modelo para o documento de estrutura está em references/template.md. Em caso de dúvida sobre formatação, siga-o.

Acordo com o skill de criação de slides (regras herdadas do progress-report-deck)

O documento de estrutura deve seguir estas regras. Caso contrário, slides podem ser cortados ou refeitos.

Item	Regra	Motivo (regra do progress-report-deck)
Título	1 ## = 1 slide. Não use ## para nada que não seja slide. Use # para separar capítulos	O rascunho lê ## como slide
Estrutura	Título → O que foi feito (índice) → Contexto da pesquisa (1/2)(2/2) → Objetivo da pesquisa (meta atual) → Conteúdo → Resumo e próximos passos → Agradecimentos, nessa ordem	Template fixo
Contexto	Se não mudou desde a última apresentação, escreva apenas "Mantido (conforme material base)"	Contexto geralmente é mantido
Meta atual	No slide de objetivo, inclua obrigatoriamente a frase "Meta atual desta etapa" (1-2 linhas)	O skill pergunta isso ao usuário a cada vez; é melhor já definir
Número de slides	Escreva com o número final de slides (para que o outro skill não precise juntar ou dividir)	O outro skill sugere juntar se houver muitos ##
Layout	Para cada slide de conteúdo, especifique um tipo de layout (tabela abaixo)	Se apenas jogar tópicos, o skill reclama que "metade inferior está vazia"
Cores	Apenas dois significados: Azul = proposta/resposta/conclusão/valor principal, Laranja = método anterior/problema/observação/atenção. Não atribua uma terceira cor por método. Em tabelas, destaque a linha principal como "realçada em azul claro"	Tema usa apenas azul #156082 e laranja #E97132
Quantidade de texto	Ideia principal máx. 30 caracteres (caracteres largos) (cabe em uma linha com fonte 18pt). Cada item de tópico também deve ter ~30 caracteres. Máx. 3 linhas por painel. Se ficar longo, use figura/tabela ou divida o slide	Fonte mínima 16pt; não é permitido reduzir para encaixar
Tamanho da fonte	Não escreva instruções como "pequeno" ou "nota em fonte menor". Notas de rodapé devem caber em uma linha com 16pt	Fonte abaixo de 16pt é proibida
Fórmulas	Escreva com $...$ (LaTeX) e indique "Fórmula (OMML)"	Fórmulas são compostas em OMML
Figuras	Copie os PNGs para images/ na pasta de saída e referencie como images/<nome>.png (se só houver PDF, converta para PNG). Não use caminhos dentro do repositório ou ../. Verifique se cabem em slides 4:3 (ex.: coloque 2 figuras largas uma sobre a outra)	PPTX usa PNG. Slides são 4:3. O slide pode ser gerado em outra pasta ou máquina, que não enxerga pastas externas
Diagramas	Para diagramas sem arquivo de figura (fluxo, timeline, comparação antes/depois), especifique o tipo e a descrição de como desenhar	Para que o outro skill não precise perguntar ao usuário como tratar figuras
Notas	Conteúdo falado vai em "Notas do apresentador". Não coloque no slide	—
Suplementos	Slides de suporte para perguntas vão após "Agradecimentos"	Encerramento é o final da apresentação principal

Tipos de layout disponíveis (exemplos em assets/template.pptx do progress-report-deck):

Tipo	Quando usar	Exemplo no template.pptx
Chip + Painel (problema → solução)	"Problema anterior → solução atual", "Observação → resposta"	p.7, p.11
Selo numerado + Painel	Enumeração de itens com ①②③ (vantagens, etapas)	p.8-9
Diagrama Before/After	Comparação método anterior vs. proposto (esquerda = borda laranja, direita = borda azul, seta entre eles)	p.10
Diagrama de Timeline	Fluxo temporal (caixas com linha sólida/tracejada + conectores)	p.12
2 colunas Chip + Painel + Faixa inferior	Comparar dois métodos/configurações lado a lado, com fórmula	p.13
Tabela + Faixa largura total	Tabela de resultados com faixa abaixo interpretando	p.14
Blocos KPI (2×2)	Mostrar 4 valores ou conclusões em destaque	p.15
Lista de verificação (✓)	Enumeração de itens verificados ou realizados	p.16
Caixa com moldura (2 linhas)	Resumo / perspectivas futuras	p.17
Figura + Faixa largura total	Figura grande com faixa de interpretação abaixo	(substitui tabela da p.14)

O índice ("O que foi feito") não recebe tipo de layout (apenas lista de tópicos, com palavras-chave em negrito, sem cores).

Procedimento

1. Perguntar requisitos (AskUserQuestion, de uma vez)

Não pergunte o que já está claro pelo contexto. Pergunte apenas o que faltar.

• Tipo de apresentação e duração: Relatório de progresso / Seminário / Congresso. Estimativa: 1 slide de conteúdo ≈ 1 minuto (ex.: para 15 min, ~10 slides de conteúdo + 5-6 da estrutura)
• Público: Membros do laboratório / Congresso / Pessoas de outras áreas. Isso muda o nível de conhecimento prévio
• Informações contextuais a incluir (múltipla escolha): Motivação/histórico, Experimentos comparativos, Análise de falhas, Evolução do método, Impacto de correções de bugs, etc. Os tópicos devem ser sugeridos com base no que foi encontrado nos registros
• Manter contexto da pesquisa igual?: Se for mudar em relação ao material anterior, especificar o que mudar

Se o usuário responder com texto livre não previsto nas opções, trate como requisito (ex.: "Inclua também X como motivação").

2. Coletar materiais (apenas leitura; não reexecutar experimentos)

• Skill de criação de slides: ${CLAUDE_SKILL_DIR}/../progress-report-deck/SKILL.md (verificar o acordo acima)
• Registros: 実行記録_*.md, *結果*.md, README.md, documento de diretrizes, etc. Comece pelos mais recentes
• Valores: summary/*.csv, tabelas em *.md. Transcreva os valores para a apresentação sempre a partir daqui
• Figuras: Procure PNGs existentes com ls. Dê preferência a figuras com rótulos em japonês. Anote o caminho original de cada figura usada (para copiar para images/ no passo 4 e citar a fonte)
• Hiperparâmetros/constantes: Para slides de suporte, obtenha os valores reais do código (constantes, defaults do argparse, JSON de configuração salvos na execução), não dos registros. Se houver discrepância entre registro e código, prevalece o código, e informe o usuário

3. Definir a estrutura

Estrutura (seguindo o template do progress-report-deck):

1. Título
2. O que foi feito (índice; lista resumida dos títulos dos slides de conteúdo)
3. Contexto da pesquisa (1/2)
4. Contexto da pesquisa (2/2)
5. Objetivo da pesquisa (objetivo + meta atual)
6. ~ Slides de conteúdo
7. Resumo e próximos passos
8. Agradecimentos
9. Slides de suporte (para perguntas)

Os slides de conteúdo geralmente seguem esta ordem (ajuste conforme o número de slides):

1. Motivação / problema (por que fez isso) → Chip + Painel
2. Proposta / mudança e vantagens → Diagrama Before/After ou Selo numerado + Painel
3. Detalhes do método (fluxo) → Diagrama de Timeline
4. Garantia de corretude / verificação → Lista de verificação
5. Definição de parâmetros → Blocos KPI ou Tabela + Faixa
6. Configuração experimental (dados, métodos de comparação, métricas) → 2 colunas ou Tabela + Faixa
7. Resultados (1 slide por conclusão principal) → Tabela + Faixa, Figura + Faixa
8. Custo / restrições → Tabela + Faixa ou Blocos KPI

Inclua sempre slides de suporte (para perguntas), que não entram na contagem de tempo da apresentação.

• Configurações detalhadas (modelo, otimizador, constantes em tabela)
• Configurações dos dados / simulação
• Detalhes dos métodos de comparação (fórmulas com OMML)
• Definição rigorosa das métricas
• Tabela completa de resultados (ex.: busca de parâmetros)
• Perguntas esperadas e respostas sugeridas (cerca de 8): Não colocar em slides (# como capítulo, no final do documento, para uso do apresentador). Priorize perguntas que explorem pontos fracos: "A diferença não é pequena?", "Dá para concluir com uma única execução?", "Por que esse baseline?", "Custo computacional?", "Qual a evidência para afirmações não verificadas?", etc.

4. Escrever (agrupar em pasta e gerar saída)

Os slides podem ser gerados pelo progress-report-deck em outra pasta ou outra máquina (ex.: PC com PowerPoint). Portanto, agrupe o documento de estrutura e as imagens em uma única pasta, de modo que apenas essa pasta seja necessária para gerar os slides.

DocumentoSlides-<data>/
├── DocumentoSlides-<data>.md   ← Documento de estrutura
└── images/
    ├── speed_sweep.png
    └── ...

• Nome da pasta e do arquivo .md: DocumentoSlides-<data> (ex.: DocumentoSlides-2026-10-15/). A data é a de criação no formato YYYY-MM-DD. Se no mesmo dia houver outra apresentação e houver conflito de nomes, adicione um identificador curto após a data (ex.: DocumentoSlides-2026-10-15-seminario/). Não sobrescreva pastas existentes. Crie na raiz do projeto
• Imagens: Copie todas as figuras usadas para images/ (cópia, não mova; não altere os arquivos originais)
  • Mantenha o nome original. Se houver conflito de nomes ou nomes pouco descritivos (ex.: fig1.png), renomeie para um nome alfanumérico descritivo (ex.: velocity_field_f195.png). Não use espaços
  • Se a figura só existir em PDF, converta para PNG (ex.: pdftoppm -png -r 200 -singlefile in.pdf images/name, ou PyMuPDF a 200 dpi)
  • No documento de estrutura, referencie como images/<nome>.png
  • No capítulo "Fontes", registre o caminho original no formato "images/xxx.png ← caminho original" (para rastreabilidade ao refazer a figura)
• Diagramas (sem arquivo de figura) não geram imagem; apenas descreva como desenhar no documento

No início do documento (capítulo # "Sobre este documento", que não é slide), inclua instruções para o progress-report-deck:

• Tipo de apresentação, duração, número de slides, público
• Formatação de cada slide (abaixo)
• Não alterar ou arredondar valores numéricos
• Usar esta pasta como diretório de trabalho para o progress-report-deck. As figuras estão em images/ e são referenciadas como images/<nome>.png. Não criar novas figuras (diagramas devem ser desenhados conforme especificado)
• Regras de notação de nomes de métodos, atribuição de cores (azul = proposta, laranja = método anterior / comparação)
• Se o contexto da pesquisa será mantido ou não

Formatação de cada slide:

## Slide N — <Título>

- **Layout**: <Tipo de layout (um da tabela acima)>
- **Ideia principal**: <Uma frase de até 30 caracteres (caracteres largos) com a conclusão principal deste slide>
- **Conteúdo**: <Lista de tópicos. Cada item ~30 caracteres, até 3-4 itens>
- **Tabela** / **Figura**: <Tabela em Markdown, indicando linha/coluna a destacar. Figura: `caminho_relativo.png` (do que se trata)>
- **Fórmula (OMML)**: <se houver, em $...$>
- **Notas do apresentador**: <O que falar; não colocar no slide>

Regras ao escrever:

• A ideia principal deve ser uma conclusão. Não escreva "Resultado ①", "Sobre X" ou "Mostra X"; escreva "A diferença aumenta com a velocidade". Não use tratamento formal ("です・ます" em japonês)
• Palavras de avaliação devem ser justificadas numericamente. Se usar "significativamente", "eficaz", "superior", coloque no mesmo slide o comparativo, a métrica e o número de tentativas. "Equivalente" e "garantido" são exagerados facilmente; prefira "quase equivalente" ou "confirmado"
• Evite palavras comuns em texto gerado por IA: "muito", "inovador", "é possível", "perfeitamente", etc. Consulte ${CLAUDE_SKILL_DIR}/../progress-report-deck/references/ai-smell-lexicon.md para lista e substitutos
• Cada item de tópico deve conter uma frase completa (se houver duas orações ligadas por ponto final, separe em dois itens)
• Declarações não verificadas devem ser marcadas como tal. Não misture propriedades esperadas com o que foi demonstrado experimentalmente. Inclua uma linha no slide ou na faixa, e coloque também na seção "Resumo e próximos passos" sob "Futuro"
• Condições para comparação justa (ex.: "usando configuração convergida") devem ser escritas em uma linha de rodapé. Explicações longas de histórico só se o usuário pedir para incluir
• Detalhes que não cabem no slide vão para as notas do apresentador ou slides de suporte. Não alongue o texto do slide
• Ao final, adicione a tabela "Fontes" (conteúdo → arquivo) como capítulo #

5. Validar (obrigatório)

1. Verificação automática de valores: Extraia todos os números decimais do documento de estrutura com regex e compare com os valores nos arquivos de origem (md / CSV, considerando arredondamentos para 4 ou 2 casas decimais). Para cada valor não encontrado, verifique se é diferença calculada, erro de transcrição ou arredondamento inconsistente, e corrija. Coloque o script de verificação no scratchpad
2. Autossuficiência da pasta: Todas as referências a figuras no documento devem ser para images/ com PNGs existentes. Não deve haver ../ ou caminhos absolutos ou dentro do repositório. Também não deve haver arquivos não referenciados em images/. Informe o tamanho total da pasta
3. Conteúdo das figuras: Para cada afirmação sobre o que a figura mostra (ex.: "X é maior em Y"), abra a figura e confirme visualmente
4. Verificação automática das regras: Use o script de verificação do skill de slides:

   python "${CLAUDE_SKILL_DIR}/../progress-report-deck/scripts/check_deck.py" --text "<documento.md>" > check_doc.txt
   

   Leia a saída com Read e corrija todos os WARN (se for uma expressão correta do ponto de vista da pesquisa, pode manter). Se a última linha não for DONE: …, a verificação falhou, não considere como 0. Se o script não for encontrado, verifique manualmente
5. Contagem de slides: Verifique se o número de ## corresponde ao esperado pelos requisitos

6. Relatar

• Na primeira linha, informe o leitor previsto (ex.: "Leitor previsto: skill progress-report-deck (e, por extensão, audiência do seminário do laboratório)")
• Caminho da pasta de saída e seu conteúdo (1 md + número de imagens + tamanho total)
• Estrutura (uma linha por slide) e conteúdo dos slides de suporte
• Resultados da validação (quantidade de valores verificados, confirmação de figuras, checagem das regras)
• Pontos que o usuário deve saber antes da apresentação: Afirmações não verificadas, valores que podem ser questionados e por quê, a qual execução/código os resultados pertencem
• Próximo passo: "Basta executar o progress-report-deck nesta pasta (ou copiá-la inteira para outra máquina) para gerar os slides." Informe sobre como transportar (USB, Box/OneDrive, zip etc.) – a decisão é do usuário
• Não faça commit (a menos que solicitado)