atualizacao-pipeline-dados

name: atualizacao-pipeline-dados description: Atualizar e expandir o pipeline de dados territoriais do Tocantins (139 municipios, 10 eixos). Use sempre que o usuario mencionar "atualizar dados", "nova onda", "incorporar indicador", "refresh do pipeline", "Onda N do pipeline", ou quando uma ADR mencionar atualizacao de indicadores. Tambem ativar proativamente quando detectar referencia a indicadores obsoletos ou ao diagnostico D1-D5. type: project

Atualização do Pipeline de Dados Territoriais

Quando ativar esta skill

• Usuário menciona: "atualizar dados", "nova onda", "incorporar indicador", "refresh do pipeline", "Onda N"
• ADR menciona atualização de indicadores
• Detecção de indicadores obsoletos ou referência ao diagnóstico D1-D5
• Solicitação de extração BigQuery, SIDRA, ou downloads de dados

Contexto do pipeline

• 139 municípios do Tocantins × 10 eixos temáticos
• 3 camadas: Geoportal (G), basedosdados BigQuery (B), APIs diretas (A)
• Scripts canônicos: extrair_bigquery.py (BigQuery) + extrair_sidra.py (SIDRA) + extrair_apis_publicas.py/extrair_downloads.py/extrair_scraping.py (Onda 2)
• Guia completo: 06-dados/GUIA-PIPELINE-DADOS.md (v1.1, pós-Onda 2)
• Estado atual: 134 CSVs, ~72 indicadores, ~80% cobertura (pós-Onda 2, 2026-04-16)

Princípio orientador: basedosdados-first

Antes de classificar um indicador como scraping/download, verificar se o dataset já existe no basedosdados.org. Evidência Onda 2: 7 de 10 sucessos foram redirecionados para BigQuery em tempo de execução — CNPJ RFB, Queimadas INPE, ComexStat, CadÚnico, Leishmaniose (SIM proxy). Detalhes no GUIA §2.

Fluxo de trabalho (Ciclo A→E)

Bloco A — Planejamento (Cowork)

1. Identificar indicadores-alvo (diagnóstico D1-D5, tier, fonte)
2. Verificar disponibilidade de fontes
3. Criar ADR para a onda (ver references/template-adr.md)
4. Preparar briefing handoff (ver references/template-briefing.md)
5. Se fontes restritas: iniciar pedidos LAI em paralelo (20 dias úteis)

Bloco B — Execução (CC local)

REGRA INVIOLÁVEL: Consultar INFORMATION_SCHEMA.COLUMNS antes de qualquer query nova.

SELECT column_name, data_type
FROM `basedosdados.DATASET.INFORMATION_SCHEMA.COLUMN_FIELD_PATHS`
WHERE table_name = 'TABELA';

Sequência: 0. Pré-voo BigQuery (sempre primeiro). Rodar o doctor 06-dados/basedosdados/scripts/preflight_bq.py --doctor (ADC presente? quota_project_id? import basedosdados? SELECT 1?). ADC é passo HUMANO, 1×/máquina (gcloud auth application-default login) — o CC só verifica, nunca faz login interativo; se ausente, PARA com instrução. Usar o venv canônico .venv-bq (PEP 668: não pip install no sistema). bq CLI ≠ ADC. Detalhes/endurecimento: CLAUDE.md §Extração + 06-dados/GUIA-PIPELINE-DADOS.md.

1. Verificar schema real das tabelas-alvo
2. Adicionar queries ao extrair_bigquery.py com tags ("tags": ["ondaN", "tematica"])
3. Executar (via venv): .venv-bq/bin/python extrair_bigquery.py --projeto gen-lang-client-0139966355 --tag ondaN
4. Backup de CSVs existentes antes de sobrescrever
5. Encoding SEMPRE utf-8-sig

Bloco C — Validação (Cowork)

Usar checklist completo em references/checklist-validacao.md. Resumo:

• 139 municípios únicos (ou justificar cobertura parcial)
• Zero bytes NUL, zero cod_ibge vazio
• Sanity-check em Palmas
• Planejar 2-3 iterações

Bloco D — Integração (Cowork)

1. Review relatório de saída do CC
2. Deliberar sobre recomendações
3. Atualizar memórias + inventário
4. Orientar commit/push/PR

Bloco E — Checkpoint (Cowork)

1. Registrar marcos em state.md
2. Atualizar GUIA-PIPELINE-DADOS.md com novos pitfalls
3. Identificar itens para próxima onda

Pitfalls críticos (resumo)

Consultar references/pitfalls-schema.md para lista completa (P1-P14). Os mais perigosos:

1. idade no SIM é FLOAT64 — usar idade < 1, nunca idade = 0 (P1)
2. sigla_uf não existe em todas as tabelas — usar SUBSTR(id_municipio, 1, 2) = '17' (P4)
3. Mortalidade infantil: SINASC como tabela mestre + LEFT JOIN SIM (P9)
4. Escrita: SEMPRE open('w', encoding='utf-8-sig'), nunca open('r+b') (P8)
5. Leitos CNES: quantidade_total (não quantidade_leito_existente) (P7)
6. Campos categóricos (sexo, etapa_ensino, etc.): rodar SELECT DISTINCT antes de filtrar — códigos frequentemente divergem do sistema-mãe (P10, P11)
7. APIs obsoletas (INPE queimadas, Firjan IFDM): preferir basedosdados; IFDM é estático pós-2018 (P12, P13)
8. TabNet DATASUS: encoding latin-1 + DEF pode não existir → tentar basedosdados primeiro (P14)

Referências

• 06-dados/GUIA-PIPELINE-DADOS.md — guia completo
• references/checklist-validacao.md — checklist Bloco C
• references/template-briefing.md — template briefing Cowork→CC
• references/template-prompt-cc.md — prompt pronto para CC local
• references/pitfalls-schema.md — pitfalls BigQuery completos
• references/template-adr.md — template ADR nova onda