SKILL

Skill — data-dictionary-prep

Skill secundária do Screener. Só é invocada após folder-inventory rodar e o operador escolher pastas para virar dicionário de dados.

Quando aplicar

Triggers (sempre com aprovação explícita por pasta):

• “extrair estrutura das planilhas em ”
• “preparar candidatos a dicionário em ”
• “quero ver as abas e colunas das XLSX dessa pasta sem ler valores”

Não aplicar quando:

• a pasta não foi explicitamente aprovada por Pedro nesta sessão
• a pasta é sensível (folha, RH, jurídico pessoal, etc) — esta skill nunca opera em pasta sensível, mesmo aprovada
• não houve folder-inventory rodado antes (precisa do inventory.json como base)

Pré-condições

1. operador é Pedro ou Rafael Rossetto
2. existe inventory.json recente (gerado em ≤30 dias) para a pasta
3. operador escreveu, no chat ou no manifest, a frase explícita: aprovo abrir cabeçalhos em <caminho-da-pasta>
4. a pasta não está flagged como sensível em 05_anomalias.md

Procedimento

Passo 1 — confirmação tripla

1. exibir ao operador o caminho exato da pasta a abrir
2. listar quantos arquivos serão lidos (apenas headers) por extensão
3. estimar tempo (segundos por arquivo: ~0.2s xlsx, ~0.5s pptx/docx/pdf)
4. pedir confirmação literal: digite "abrir headers de <pasta>" para confirmar

Sem confirmação literal, parar.

Passo 2 — extração (apenas estrutura)

Para cada arquivo da pasta autorizada:

XLSX

• abrir com openpyxl em read_only=True, data_only=True
• capturar: nome do arquivo, nomes das abas, número de linhas e colunas por aba, nomes das colunas (primeira linha de cada aba)
• não capturar: nenhum valor de célula além da primeira linha
• nunca executar fórmulas

PPTX

• abrir com python-pptx
• capturar: nome do arquivo, número de slides, título de cada slide (somente texto do shape de título, se existir)
• não capturar: corpo de slide, notas, imagens, comentários

DOCX

• abrir com python-docx
• capturar: nome do arquivo, número de páginas (estimado), Heading 1 e Heading 2 (apenas texto do heading)
• não capturar: corpo, comentários, tracked changes, autoria

PDF

• abrir com pypdf em modo strict=False
• capturar: nome do arquivo, número de páginas, bookmarks/sumário (se existirem)
• não capturar: texto do corpo, anotações, formulários preenchidos

Passo 3 — ficha por arquivo

Para cada arquivo, gerar uma ficha em outputs/<...>/04_candidatos-dicionario/<arquivo-slug>.md:

---
arquivo: "<nome>"
caminho: '<caminho-relativo-ao-root>'
formato: xlsx | pptx | docx | pdf
tamanho_bytes: <num>
data_modificacao: "<ISO 8601>"
captura: headers-only
captura_em: "<ISO 8601>"
operador: pedro | rafael
---
 
# <nome>
 
## Estrutura observada
 
[Para XLSX: lista de abas; para cada aba, lista de colunas e nº de linhas]
[Para PPTX: lista numerada de títulos de slide]
[Para DOCX: lista de Heading 1 + Heading 2]
[Para PDF: lista de bookmarks com profundidade]
 
## Hipótese de uso
 
[1 a 3 frases. Marcar como hipótese.]
 
## Candidato a entidade do lake?
 
- entidade hipotética: <nome>
- granularidade: <imóvel / cliente / contrato / período / outro>
- chave provável: <coluna ou identificador>
- camada provável: bronze | silver | gold
 
## Perguntas a confirmar com a Colliers
 
- 1.
- 2.
 
## Notas

Passo 4 — consolidação

Atualizar 04_candidatos-dicionario.md (raiz da execução) com:

• tabela resumo: arquivo, formato, abas/seções, candidato a entidade, hipótese de granularidade
• ranking sugerido: top 10 candidatos para virar fonte de dados, com justificativa em 1 linha cada

Passo 5 — verificação anti-leak

Antes de fechar:

1. grep -i -E '\b[0-9]{3}\.[0-9]{3}\.[0-9]{3}-[0-9]{2}\b' (CPF) em todas as fichas geradas — deve retornar zero
2. grep -i -E '\bR\$ [0-9]' (valores em real) em todas as fichas — deve retornar zero
3. grep -i -E '@(colliers|costal)\.com' em todas as fichas — deve retornar zero (nomes de coluna não devem incluir e-mail)
4. checar tamanho das fichas: ficha que passar de 5KB precisa ser revisada manualmente (pode ter capturado conteúdo demais)

Se algum check falhar, parar, registrar em 05_anomalias.md, e remover as fichas em questão.

Outputs esperados

• outputs/<...>/04_candidatos-dicionario.md (consolidado, atualizado)
• outputs/<...>/04_candidatos-dicionario/<arquivo-slug>.md (uma ficha por arquivo)

Limites duros

• nunca capturar valor de célula, parágrafo de texto, conteúdo de slide ou anotação
• nunca operar em pasta sem aprovação literal escrita do operador
• nunca operar em pasta flagged como sensível
• abortar se grep anti-leak (CPF, R$, e-mails) detectar match
• nunca executar macro de Excel ou abrir arquivo em modo de escrita

Falhas conhecidas

• XLSX corrompido ou versão antiga (xls). openpyxl falha. Solução: registrar em 05_anomalias.md e pular.
• PPTX com título dentro de imagem. python-pptx não captura. Solução: marcar slide como “sem título estruturado”.
• DOCX antigo (.doc). python-docx não abre. Solução: registrar e pular.
• PDF protegido por senha. pypdf falha. Solução: registrar e pular.

Ver também

• Skill folder-inventory
• Guardrails do Screener
• Runbook do Screener — passo “modo dicionário”