Skill: ml-checkpoints

Conduz o pipeline preditivo por checkpoints. Em cada um, você pergunta o caminho, oferece só o que os dados permitem, registra a escolha com o motivo e segue.

A skill existe porque a decisão errada em ML de saúde quase nunca é a do modelo. É separar por linha quando o mesmo paciente tem três internações, imputar sem indicador uma variável que falta mais em quem tem menos acesso, usar AUROC com desfecho de 3%, ou tratar código de município como quantidade. Nenhum desses erros aparece na métrica: todos aparecem na validação externa, quando já não dá para voltar.

Por isso a regra que organiza tudo: as opções de cada checkpoint saem do diagnóstico da base, não de um menu fixo. Se os dados bloqueiam uma estratégia, ela não é oferecida.

Fluxo

CP0 diagnóstico -> CP1 desfecho -> CP2 separação -> CP3 faltantes -> CP4 pré-processamento
 -> CP5 desbalanceamento -> CP6 modelos -> CP7 features -> CP8 métrica -> CP9 calibração
 -> CP10 interpretabilidade -> CP11 predição e empacotamento

Um checkpoint por vez. Não adiante decisão futura nem peça tudo de uma vez: o valor está em cada escolha chegar com o número que a sustenta.

CP0: diagnóstico (sempre primeiro, sem perguntar antes)

Peça o caminho da base e a coluna do desfecho, e rode:

python "${CLAUDE_SKILL_DIR}/scripts/diagnose_data.py" <arquivo> --target <desfecho> [--id <coluna>] [--date <coluna>]

O Claude Code já entrega o caminho entre aspas resolvido para a pasta desta skill, venha ela do plugin ml do marketplace labdaps ou do install.sh. Se aparecer o nome da variável no lugar de um caminho, use ~/.claude/skills/ml-checkpoints/, a pasta da instalação pelo install.sh. Aceita CSV, TSV, Parquet e Excel. Com --json, devolve o mesmo diagnóstico em formato de máquina.

O que ele mede e por que cada coisa importa está em references/checkpoints.md. O essencial: N e colunas, tipo e prevalência do desfecho, missing por coluna, cardinalidade, sentinelas de saúde (9, 99, 999) distinguidas de código legítimo, colunas numéricas que na verdade são código, repetição por identificador, colunas de data e suspeita de vazamento por AUC univariada.

Apresente ao usuário só o que exige decisão, não o relatório inteiro. E leve a sério o que aparecer:

• Suspeita de vazamento é parada obrigatória. Uma variável com AUC univariada acima de 0,95 quase sempre é consequência do desfecho, não preditora. Resolva antes do CP1.
• Missing no próprio desfecho muda a definição da coorte, não é problema de imputação.
• Repetição por identificador já elimina o split aleatório, e isso precisa ser dito no CP2 com o número de linhas por grupo.

Como conduzir cada checkpoint

1. Nunca ofereça opção marcada BLOQUEADO pelo diagnóstico. Ela não é uma escolha ruim, é uma escolha que os dados impedem. Se o usuário pedir mesmo assim, mostre o número que a bloqueia e peça confirmação explícita antes de registrar como aceite consciente.
2. Duas a quatro opções, cada uma com o que ela custa. A recomendada vem primeiro, marcada, e o motivo é sempre um número medido na base, nunca "é boa prática".
3. Registre a decisão em pipeline-decisions.md assim que ela for tomada, a partir de templates/pipeline-decisions.template.md. Esse arquivo vira a seção de Métodos do artigo: se a decisão não estiver escrita com o motivo, ela não existe daqui a três meses.
4. Propague a restrição. Toda escolha fecha portas adiante, e isso precisa ser dito na hora, não descoberto depois.

Restrições que uma escolha impõe às seguintes

Quando uma escolha reabre um checkpoint anterior, volte, refaça e anote no registro. Seguir em frente com a decisão velha é o caminho mais curto para um resultado que não reproduz.

Os checkpoints

O catálogo completo de opções, com o critério que muda o status de cada uma, está em references/checkpoints.md. Resumo do que se decide:

CP11: fechar o ciclo

Com todas as decisões tomadas, gere o código do pipeline refletindo exatamente o que foi escolhido, rode, e entregue quatro coisas:

1. A predição no dado que o usuário quer prever, com a probabilidade calibrada, não só a classe.
2. A métrica principal com intervalo de confiança, comparada com a baseline do CP6. Sem a baseline ao lado, o número não significa nada.
3. O SHAP com a direção de cada variável, com as divergências do esperado clinicamente marcadas.
4. O pipeline-decisions.md completo, que já é o rascunho da seção de Métodos.

Se o modelo não bater a baseline, diga isso na primeira linha. Resultado negativo fecha o ciclo, não reabre a busca por um número melhor.

Regras que não dependem do checkpoint

• Separar antes de ajustar qualquer coisa, e todo pré-processamento aprendido dentro do fold. Imputação, encoding, escalonamento, seleção, balanceamento e busca de hiperparâmetros só veem a partição de treino. Aprender no dado completo infla a métrica de um jeito indistinguível de sucesso.
• Dado bruto nunca no repositório. O registro de decisões referencia o caminho, jamais o conteúdo.
• Nada de escolher o corte olhando o teste.
• Métrica sem incerteza não é resultado. Reporte IC, por bootstrap ou pela variação entre folds.

Relação com as outras skills do laboratório

Esta skill decide, as outras executam. Ela é o passo a passo interativo; a graph-lab é o planejamento do experimento inteiro como grafo antes de começar, e a ml-pipeline é a implementação padrão do laboratório.

Esta skill é a norma de método do laboratório: as outras apontam para ela em vez de repetir regra própria. A evidência por trás das regras, o que já deu errado em projeto e por quê, está em docs/aprendizados-pipeline-agentes.md, no ai-lab-hub.

Referências

• scripts/diagnose_data.py: o diagnóstico que alimenta as opções (pandas e numpy)
• references/checkpoints.md: catálogo de opções por checkpoint, com o critério de cada status
• templates/pipeline-decisions.template.md: registro das decisões, que vira a seção de Métodos