Skill: spec

Transforma um pipeline em documento que a pessoa que vai apresentar consegue defender.

O problema que ela resolve: o codigo roda, os numeros saem, e a pessoa que precisa explicar na banca nao escreveu nenhuma linha. Ela sabe o resultado e nao sabe por que cada decisao foi tomada, entao nao consegue responder "por que voce usou Boruta?" nem "por que 622 e nao 775?".

Regra central: nada entra no documento que nao exista no codigo ou no log. O esqueleto sai do extrair_spec.py, que le o pipeline com o parser do Python e a saida da execucao. Se um passo nao esta no codigo, ele nao vira paragrafo. Se um numero nao esta no log, ele nao vira tabela. E o que impede o documento de descolar do pipeline na primeira alteracao.

Segunda regra: o documento e escrito para quem vai apresentar, nao para quem escreveu. Quem escreveu ja sabe. O teste de qualidade e uma pergunta: se a banca perguntar "por que", a resposta esta no documento?

Fluxo

1. Extrair o esqueleto

python "${CLAUDE_SKILL_DIR}/scripts/extrair_spec.py" > spec_esqueleto.md      # na raiz do projeto

Sai de la, verificavel:

Se o extrator apontar buraco, conserte no codigo primeiro. Documento que explica o que o codigo nao faz e pior que documento nenhum.

2. Escolher o leitor

Antes de escrever, defina em uma linha quem le e o que essa pessoa precisa conseguir fazer depois de ler. Muda tudo:

• orientanda que vai defender: precisa do porque de cada decisao e das ressalvas, com as frases prontas para responder a banca.
• coautor clinico: precisa do desenho, do que o numero significa clinicamente e do que nao se pode concluir. Nao precisa de nome de funcao.
• revisor ou banca: precisa do metodo reproduzivel, das premissas e das limitacoes.
• outro pesquisador do lab que vai reusar: precisa de como mudar e rodar de novo.

3. Escrever

Estrutura em "${CLAUDE_SKILL_DIR}/templates/spec_template.md". As secoes que nunca saem:

1. A pergunta e a decisao. O que se prediz, para quem, em que momento, e que decisao clinica o resultado informa. Uma frase cada.
2. As regras. A tabela de parametros, cada um com o porque. Esta e a parte "spec": quem le consegue dizer "quero 10 repeticoes em vez de 5" e sabe exatamente o que muda.
3. O passo a passo. Uma secao por etapa, na ordem em que roda. Cada uma responde tres perguntas, nesta ordem: o que faz, por que existe, e o que aconteceria sem ela. A terceira e a que ensina, e e a que a banca pergunta.
4. O que foi testado e como se sabe que funcionou. Nao "foi validado", e sim qual verificacao rodou, o que ela teria pego, e o que ela nao pega. Bug encontrado no caminho entra aqui: e a prova de que a verificacao serve para alguma coisa.
5. Os numeros. Direto das tabelas de results/, com intervalo de confianca quando existir.
6. O que nao se pode concluir. Tamanho de amostra, ausencia de validacao externa, confusao residual, comparacao entre coortes diferentes. Escrito como frase que a pessoa pode falar.
7. Como rodar de novo e como mudar. Comandos e o que cada parametro faz.

Escreva em portugues direto, sem jargao que o leitor nao precise. Nome de funcao so aparece quando a pessoa vai precisar procurar no arquivo.

4. Entregar

Escolha pelo destino, e pergunte se nao estiver claro:

Email nunca sai sem confirmacao. Mostre o rascunho inteiro, com destinatario e assunto, e espere o "pode mandar". Isso vale mesmo quando o pedido original ja dizia "manda um email": o pedido autoriza escrever, o envio e um segundo passo.

O corpo do email nao e o documento inteiro. E o convite para ler: o que foi feito em um paragrafo, o resultado em uma frase, as duas ou tres coisas que a pessoa precisa saber para apresentar, e o link. O documento completo vai anexo ou linkado.

O teste do documento

Antes de entregar, responda como se fosse a banca:

• Por que essa coorte e nao a coorte inteira?
• Por que esse desfecho?
• Por que esse algoritmo, e por que nao o mais simples?
• Como voce sabe que nao tem vazamento?
• Por que eu deveria acreditar nesse numero?
• O que esse trabalho nao prova?

Se alguma resposta nao estiver no documento, ele nao esta pronto.

Referencias

• scripts/extrair_spec.py: extrai o esqueleto verificavel do pipeline e da execucao
• templates/spec_template.md: a estrutura do documento