O que research-log faz?
Documenta pesquisas do jeito que engenheiros as recontam depois: uma história de medições, uma especificação precisa o suficiente para ser reimplementada a partir dela, um registro de verificação com números e uma lista honesta do que ainda é desconhecido — entregue como um único arquivo HTML autocontido (CSS e imagens embutidos, sem assets externos).
O compromisso central: toda reivindicação é ou baseada em uma medição, marcada como não comprovada ou listada como em aberto. A frase guia, se você precisar de uma: ler os artefatos diz o que alguém escreveu; só o sistema real diz o que isso significa.
Fluxo de trabalho
1. Faça o inventário das evidências primeiro
Colete, antes de escrever qualquer coisa, a partir da conversa, repositório, logs e do usuário:
- a cronologia: datas, o que foi tentado, o que falhou, o que surpreendeu
- toda medição com números exatos e como foi obtida
- execuções de verificação: o que foi comparado com o quê, e as figuras de erro
- as ferramentas, caminhos de arquivo e comandos que alguém precisa para repetir o trabalho
- perguntas não resolvidas e hipóteses puras
Não invente medições, datas ou números. Se um número estiver faltando, pergunte ou marque-o como OPEN. Um relatório com dados inventados é pior do que nenhum relatório — lacunas no registro fazem parte do registro.
2. Aprenda as convenções
Leia references/style-guide.md antes de escrever — o estilo vive nos detalhes (legendas que provam um ponto, falhas mantidas na narrativa, números exatos, sem marketing). Leia references/content-format.md quando estiver pronto para escrever o módulo de conteúdo.
3. Escolha o esqueleto
Seis seções principais, numeradas, nesta ordem. Omita uma apenas por um motivo declarado; insira seções de estudo de caso entre a especificação e as ferramentas quando houver um arco de "construção da coisa real".
| # | seção | deve conter |
|---|---|---|
| 1 | A história | linha do tempo dia a dia; cada etapa atribuída a uma medição; becos sem saída e surpresas incluídos |
| 2 | Método | uma frase de epistemologia + a tabela: artefato de teste → pergunta → resposta |
| 3+ | A especificação | tabelas de byte/protocolo/formato precisas o suficiente para reimplementar, com tags de confiança; a matemática como blocos de código |
| −2 | Ferramentas e como fazer | comandos e caminhos reais que funcionam quando copiados textualmente |
| −1 | Registro de verificação | toda execução de medição com erros quantitativos + um destaque Resultado final |
| −0 | Perguntas em aberto | incógnitas honestas, cada uma marcada OPEN ou HYP |
4. Escreva e construa
Escreva o conteúdo como um módulo Python definindo DOC (formato em references/content-format.md), mantenha-o no projeto para que o documento possa ser regenerado, então:
python3 <skill-dir>/scripts/build_doc.py content.py out.html
Abra a saída e verifique se ela renderiza antes de mostrar ao usuário.
5. Autoauditoria
- toda reivindicação factual carrega uma tag ou está no registro de verificação
- a história inclui pelo menos uma surpresa, falha ou correção — se o trabalho não teve nenhuma, diga isso claramente em vez de fabricar drama
- números são exatos e carregam unidades (0,445 s, não "rápido"; 64.779 pixels, não "muitos")
- toda legenda de figura afirma o que a imagem prova, não o que ela mostra
- comandos de como fazer foram realmente executados, ou estão claramente rotulados como não testados
- perguntas em aberto existem (sempre há perguntas em aberto)
- o resultado final é uma frase que alguém poderia repetir de memória
As tags
Quatro tags de confiança, colocadas em linha no final da reivindicação que qualificam:
- HW (verde) — medido no sistema real sob teste. Para trabalhos não relacionados a dispositivos, isso ainda se aplica: medido em uma execução ao vivo, na bancada, em produção.
- FILE (azul) — verdadeiro em todos os artefatos examinados (arquivos, capturas, logs).
- HYP (roxo) — consistente com todas as evidências, mas não comprovado.
- OPEN (cinza) — desconhecido; nenhuma evidência de qualquer lado.
Fatos carregam tags; comentários não. Se o domínio tiver nomes melhores para estas, renomeie-os uma vez no topo do documento e use-os consistentemente — mas mantenha exatamente esta divisão de quatro níveis.
Tom
Engenheiro colega, primeira pessoa do plural, zero marketing. Números exatos com unidades. Frases curtas. Humor seco e raro. Falhas e correções pertencem à história, não a uma nota de rodapé. Colegas são creditados por função ("um colega entregou duas sequências PNG…").
Origem
Destilado do registro de pesquisa TriCaster DVE (waldobjekt.org, 1–3 de novembro de 2026, escrito com Claude) — o documento original traz seu próprio build_doc.py; este skill generaliza essa configuração.