Pbi Modelo Review

/pbi-modelo-review — Auditoria de modelo Power BI

> 📦 Distribuída publicamente: github.com/xperiun/claude-code-powerbi-skills — pasta claude-code/pbi-modelo-review/ (skill nativa) + claude-web/pbi-modelo-review.zip (upload no Claude.ai). Mudança aqui exige sincronizar lá: atualizar pasta + regenerar ZIP (Python zipfile, ver CLAUDE.md) + commit + bump CHANGELOG. Repo é open-source, leiame público — evitar referências internas (Xperiun-only) na SKILL.md.

Audita um projeto Power BI (formato PBIP) e devolve relatório priorizado com:

• Score geral (0–100)
• Issues agrupados por severidade (crítico / médio / leve)
• Distribuição por categoria (6 famílias de check)
• Cada issue com: o que é, onde está, por que importa, como corrigir (snippet quando aplicável)

Quando usar

• Analista herdou um .pbix e quer mapa rápido de qualidade
• Líder de dados pedindo auditoria antes de escalar/migrar modelo
• Consultor entrando em cliente novo
• Pré-handoff entre times
• Você quer um "linter" rodando antes de subir pra produção

Não usar quando:

• Quer apenas documentação descritiva → use /pbi-doc
• Quer criar uma medida nova → use /pbi-dax-create
• Quer otimização de performance específica de uma query (skill futura /pbi-perf)

Pré-requisitos

1. Projeto em formato PBIP (Power BI Project) — pasta com .SemanticModel/ e .Report/. Se o usuário só tem .pbix, instruir conversão antes de prosseguir:

• Power BI Desktop → File → Save as → Power BI Project (.pbip)

1. Acesso aos arquivos .tmdl (via filesystem ou upload — ver "Modos de execução" abaixo)

Se faltar PBIP, retornar mensagem curta: > Esse projeto ainda está em .pbix (binário). Pra eu auditar, salva como Power BI Project: File → Save as → Power BI Project (.pbip). Vira uma pasta de texto e aí eu consigo ler. Avisa quando converter.

E encerrar — não tentar rodar nada.

Modos de execução

A skill detecta automaticamente o ambiente e adapta input/output:

Modo Code (Claude Code · Desktop · file-based)

• Detecção: tenho acesso a filesystem do usuário e a pasta atual contém .SemanticModel/
• Input: leio automaticamente os .tmdl da pasta ./SemanticModel/
• Output: salvo em ./_review/index.html + ./_review/relatorio.md na raiz do projeto Power BI
• Idempotente: rodar 2x sobrescreve

Modo Web (Claude.ai · upload-based)

• Detecção: não tenho acesso a filesystem (claude.ai web)
• Input: peço ao usuário pra anexar os arquivos:

> Pra eu auditar, anexe nesse chat: > - Os arquivos .tmdl da pasta SemanticModel/definition/ (model.tmdl, relationships.tmdl, expressions.tmdl) > - Os arquivos da pasta SemanticModel/definition/tables/ (1 .tmdl por tabela) > > Pode arrastar todos de uma vez ou zipar a pasta SemanticModel/ e subir o ZIP.

• Output:
• HTML completo como artifact (Claude.ai renderiza inline com botão de download)
• Markdown como bloco de código copiável no chat
• Não persiste: cada conversa nova requer novo upload

Detecção automática

Verificar se a pasta .SemanticModel/ é acessível via filesystem:

• ✅ Sim → Modo Code (file-based)
• ❌ Não → Modo Web (peço uploads)

Se ambíguo, perguntar uma vez: > Você tá rodando isso no Claude Code (CLI/IDE com acesso à pasta) ou no claude.ai (web)? Pra Code eu leio a pasta sozinho; pra web preciso que você suba os arquivos.

Inputs

• Severidade mínima (opcional, default: tudo)
• tudo → reporta crítico + médio + leve
• crítico+médio → ignora leves (foco no que cobra juros)
• só crítico → só o que bloqueia produção

Se o usuário não especificar, perguntar uma vez antes de rodar: > Quer auditoria completa (todos os níveis) ou só os críticos+médios? Default é completa.

Processo

1. Detectar e mapear o projeto

• Confirmar existência de ./SemanticModel/ (ou *.SemanticModel/ na raiz)
• Listar arquivos .tmdl em ./SemanticModel/tables/
• Ler ./SemanticModel/model.tmdl, ./SemanticModel/relationships.tmdl (se existir)
• Contar: N tabelas, N medidas (varrer measure em todos os tmdl), N relacionamentos, tamanho do projeto

2. Rodar checks

Ler references/checks.md e rodar as 6 famílias de check descritas lá:

1. Modelagem — star schema, fact/dim, circular ref
2. Relacionamentos — cardinalidade, direção, ativo/inativo
3. Performance — colunas calculadas vs medidas, DISTINCTCOUNT em alta cardinalidade, etc
4. Naming — convenção, prefixos, consistência
5. DAX — DIVIDE vs /, variáveis não usadas, CALCULATE aninhado
6. Documentação — descrições ausentes, business keys

Cada check encontrado vira um issue com:

• id (slug único, ex: model-flat-detected)
• categoria (uma das 6 acima)
• severidade (critical | medium | light)
• titulo (uma frase, máx 90 chars)
• path (caminho do arquivo + linha quando aplicável)
• por_que_importa (1-2 parágrafos explicativos)
• como_corrigir (1 parágrafo + opcionalmente um snippet TMDL/DAX)

3. Calcular score

Fórmula simples:

score = max(0, 100 - (criticos × 4) - (medios × 1.5) - (leves × 0.4))

Limites:

• Score ≥ 85 → label "BOM" (gold)
• Score 65–84 → label "PRECISA ATENÇÃO" (gold)
• Score , `, ou ornamentos do template
• ❌ Gerar HTML "do zero" porque parece mais fácil — isso queima toda a identidade visual Xperiun
• ❌ Tocar em qualquer coisa dentro de comentários `` — comentários são instruções pra você, não conteúdo a substituir.
• ❌ Tocar em ... ou ... — CSS e JS ficam intocados.

1. 🚨 ENCODING — UTF-8 PURO, sem escape. Caracteres PT-BR (ã, ç, é, á, õ, ê, í, ú) e símbolos especiais (├, └, ─, →, ↔, ↑, ↓, ⚠, ·, —) devem aparecer como caracteres reais UTF-8, NÃO como sequências escapadas/HTML entities/mojibake.

• ✅ Correto: críticos, →, Atenção, ⚠
• ❌ Errado (mojibake): críticos, â, Atenção
• Sintoma: se algum acento aparece como sequência de 2-3 chars estranhos, parser HTML pode quebrar e o resto da página renderiza como texto cru. Refaz com UTF-8.

1. Garantir que CSS continua inline (sem dependências externas além das fontes Google).
2. SALVAR em ./_review/index.html (modo Code) ou retornar como artifact (modo Web).
3. Sintomas de erro:

• Cores #f5a623 (laranja) ou #7c6af7 (roxo), ou fonte 'Segoe UI' → ignorou template, refaz.
• Acentos como ã ou â → encoding quebrado, refaz UTF-8.
• Texto solto sem quebras (SVG/tabela como prosa) → mojibake quebrou parser, refaz.

6. Resumir no chat

Devolver mensagem curta no chat com:

• Score + label
• Top 3 issues críticos (apenas títulos)
• Path dos 2 arquivos gerados
• Sugestão: "Abre _review/index.html no navegador pra ver completo"

Outputs

[raiz do projeto Power BI do usuário]/
├── SemanticModel/                  ← input (não tocar)
├── Report/                         ← input (não tocar)
└── _review/                        ← OUTPUT da skill
    ├── relatorio.md                ← versão markdown (commitável)
    └── index.html                  ← versão visual standalone

Edge cases

| Cenário | O que fazer | |---|---| | Modelo sem .SemanticModel/ | Mensagem de pré-requisito (PBIP), encerra | | Pasta _review/ já existe | Sobrescrever (skill é idempotente) — mas avisar no chat | | Modelo perfeito (zero issues) | Score 100 + celebrar + listar 3 melhores patterns encontrados (já que não tem o que reclamar) | | Modelo apocalíptico (>50 críticos) | Truncar relatório nos top 30 críticos + linha "+ N issues não listados — começa por aqui antes" | | Erro lendo um .tmdl específico (corrupção) | Reportar arquivo problemático no chat, seguir com os demais | | Projeto enorme (>500 medidas) | Avisar "modelo grande, vou processar em chunks · ~5min" antes de começar |

Idempotência

• Rodar 2x no mesmo projeto sobrescreve _review/
• Não cria backups, não acumula histórico (versionamento é via Git do usuário)
• Não modifica nada em .SemanticModel/ ou .Report/ — somente leitura nesses

Segurança / Blast radius

• Lê arquivos do projeto Power BI (TMDL puro, texto)
• Escreve somente em ./_review/ (cria se não existe, sobrescreve se existe)
• NÃO toca em .SemanticModel/, .Report/, ou qualquer arquivo binário
• NÃO commita nada (segue regra inviolável git do CLAUDE.md raiz)
• NÃO faz rede — operação 100% local

Tom do relatório

Estilo Xperiun (declarado em contexto/posicionamento.md):

• Direto, sem rodeio. Verdade > conveniência
• Tom de "colega sênior revisando código", não consultor formal
• Pode ser provocativo ("isso vai cobrar juros", "modelo plano é o anti-pattern #1")
• PT-BR com todos os acentos (regra inviolável CLAUDE.md)
• Usar metáforas concretas ("vai virar ligação às 7h da manhã" > "pode causar erro em produção")

Exemplos de bom vs ruim:

❌ Ruim: "Identificou-se a presença de relacionamento bi-direcional que pode impactar negativamente a performance do modelo."

✅ Bom: "Bi-direcional em N:1 com calendário causa ambiguidade de filtro e duplica scan no engine. Em modelo de 1.4GB você está pagando ~30% de overhead por refresh sem ganhar nada."

Branding (footer e CTA do HTML)

O relatório HTML tem footer fixo:

• Linha: "Relatório gerado em 4 minutos por Claude Code + /pbi-modelo-review"
• CTA: "Quero usar esse skill no meu Power BI →" (link placeholder por enquanto)
• Meta: "XPERIUN · O Sistema Operacional dos Incomparáveis · pages.xperiun.com"

Branding é sempre Xperiun (não @leokarpa) — a skill faz parte do posicionamento institucional. Mesmo se o usuário rodar a skill no projeto dele, o footer mantém referência Xperiun (é nossa skill, ele só tá usando).

Tempo típico

• Modelo pequeno (≤30 tabelas, ≤80 medidas): 1–2 min
• Modelo médio (~50 tabelas, ~150 medidas): 3–5 min
• Modelo grande (>200 medidas, >100 tabelas): 5–10 min

Avisar ao usuário se > 3min esperados.

Versão atual

v0.1 — protótipo interno Xperiun OS. Ainda não distribuído publicamente. Quando estabilizar, vira pacote no repo xperiun/claude-code-powerbi-skills (lead magnet).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: xperiun
• Source: xperiun/claude-code-powerbi-skills
• License: MIT

Install and usage instructions live in the source repository linked above.