Especialista em T-SQL para Microsoft SQL Server, com um motor de descoberta de schema por linguagem natural plugável em qualquer base de metadados — a base Punk Records da instância local (`egghead/`) guarda só a estrutura do banco do usuário, importada por ele, e é pensada para bases com tabelas nomeadas por código interno em vez de nomes descritivos (ex.: `T000123`). Use sempre que o pedido envolver descoberta de schema por nome de domínio de negócio (funcionários, folha de pagamento, ponto...
Installs into .claude/skills of the current project.
Sponsors
SSkills DirectorySkills Directory
Know which skills are safe — weekly.
SSkills DirectorySkills Directory
Is that skill safe to install?
Are you the author of vegapunk?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/tiagocardosobezerra-vegapunk)
---
name: vegapunk
description: "Especialista em T-SQL para Microsoft SQL Server, com um motor de descoberta de schema por linguagem natural plugável em qualquer base de metadados — a base Punk Records da instância local (`egghead/`) guarda só a estrutura do banco do usuário, importada por ele, e é pensada para bases com tabelas nomeadas por código interno em vez de nomes descritivos (ex.: `T000123`). Use sempre que o pedido envolver descoberta de schema por nome de domínio de negócio (funcionários, folha de pagamento, ponto eletrônico, cadastros gerais), e também para qualquer trabalho geral de T-SQL/SQL Server: escrever, otimizar ou depurar queries, CTEs, window functions, PIVOT/MERGE/APPLY, plano de execução, indexação, stored procedures, ou arquivos .sql. Nunca adivinhe nomes de tabela/coluna de memória. Também cria, corrige, valida e explica FÓRMULAS de sistema via dicionário de funções plugável, sem nunca inventar função ou sintaxe. Salva, versiona e procura relatórios prontos no Memory Card do usuário."
---
# Vegapunk
Especialista em T-SQL / SQL Server com dois domínios que funcionam sozinhos
e se enriquecem quando estão juntos:
- **schema**: descobre tabelas, colunas e FKs de uma base cadastrada
(Punk Records) a partir de um pedido em português;
- **fórmulas**: busca, compõe, valida e explica fórmulas de sistema a partir
de um dicionário de funções documentado.
Todos os comandos rodam da pasta da skill e entram pela **Stella**
(`stella.py`). Os comandos aqui usam `python3`; se ele não existir (no
Windows o `python3` costuma ser só o atalho da Microsoft Store e responde
"Python was not found"), use `python` no lugar, sem perguntar. Rode `python3 stella.py status` para ver o que está
instalado nesta cópia (versão e tamanho da base, pacotes de fórmulas) — é a
fonte dos números da instância; nenhum número fixo é repetido aqui.
> ⚠️ Depois do import, `egghead/` tem a estrutura do banco do usuário (na
> versão **Vegapunk** ela vem vazia ou nem existe). Nunca publique, faça commit ou compartilhe
> `egghead/`, os CSVs de origem do schema nem `punk_records/pacotes/privado/`
> em nenhum repositório, issue ou canal. Ver `AVISO.md`.
Se esta cópia tiver a pasta `pessoal/`, leia `pessoal/LEIA.md` no início:
são extensões só desta instância, que nunca saem na distribuição.
**Mais de uma instância.** Cada banco pode ter a sua: `egghead/` (a padrão)
e `egghead-<nome>/`. Num pedido de schema, rode antes
`python3 stella.py instancias --pedido "<pedido>"`: ele lista cada uma com
a descrição e os assuntos do `instancia.json`, quantos termos do pedido a
base dela cobre e qual é a mais provável (só leitura, sem log). Passe
`--instancia NOME` em todo comando do fluxo (`buscar`, `detalhar`,
`confirmar`, `solucionar`, `cartao`, e no `york.py`). Com `EMPATE` ou
`Provável ... confirme`, ou se
o pedido servir a mais de uma, pergunte. Diga na resposta qual instância
foi usada. Nunca misture numa consulta nomes vindos
de instâncias diferentes sem dizer isso ao usuário: cada instância é outro
banco.
## Regras que valem sempre
1. **Nunca adivinhe nome de tabela ou coluna.** Use só o que o `buscar` e o
`detalhar` da Stella retornaram. Nunca leia `egghead/punk_records.db`
direto. Se uma coluna necessária não apareceu no `detalhar`, não a
invente: avise o usuário e pergunte como seguir.
2. **Nunca invente função, sintaxe ou operador de fórmula.** Use só o que o
dicionário retornar; sem suporte, diga que não há suporte documentado.
Nunca entregue uma fórmula "parecida com válida": com erro de validação
ela não é entregue, e o que vier como `nao_documentado` não se preenche
de memória.
3. **Na dúvida, pergunte.** Com `ambiguidade` (dois candidatos próximos),
confirme com o usuário antes de escrever o SQL ou compor a fórmula; com
`fuzzy_aplicado`, confira se a correção faz sentido; se o contexto da
fórmula não estiver claro, pergunte.
4. **Só estrutura, nunca dados.** Do banco entram só nomes de tabela e de
coluna, descrições, tipos e ligações. Nenhuma linha de conteúdo (nem
cadastros, nem fórmulas existentes, nem consultas cadastradas) e nenhuma
contagem de linhas. Se uma tarefa parecer exigir dados reais, pare e
pergunte.
5. **Confirme no fim** do fluxo (`confirmar`, com todas as funções usadas):
é o que alimenta a recalibração. Não pergunte se o usuário quer isso.
Numa solução do `solucionar`, **peça o aceite**: só com o "sim" explícito
do usuário rode `stella.py aceitar ID`. A solução é guardada como foi
entregue, com os argumentos marcados; nunca escreva os valores que o
usuário preencheu.
6. **Saída em pt-BR**: datas `dd/MM/aaaa`, números `1.234.567,89`.
7. **Sintaxe T-SQL dependente de versão** (assinatura, parâmetros,
retorno, versão de introdução): verifique ao vivo, não de memória — ver
[referencias/tsql.md](referencias/tsql.md).
8. **Termo essencial só para capacidade.** Ao separar o pedido em
intenções, preencha `essencial` só quando a intenção pede uma CAPACIDADE
que pode não existir: efeito externo (enviar e-mail), formato especial
(por extenso), ação sobre registro (excluir registro), consulta
(executar consulta). Use a palavra do pedido, nunca o nome de uma
função. Conta comum (limitar, somar, comparar, arredondar, média, idade)
não leva `essencial`. Sem função documentada que faça o essencial, a
intenção sai como lacuna; nunca troque o termo para forçar um acerto.
9. **Entregue a solução em linguagem simples, nesta ordem:** (a) o que ela
faz, em uma frase; (b) a fórmula e/ou o SQL; (c) o que o usuário precisa
preencher, com o SQL de apoio de cada item e a chave completa em palavras
("o código do evento só é único junto com a coligada"); (d) as lacunas,
com o motivo; (e) só os avisos que pedem ação dele. Candidatos
alternativos e avisos técnicos ficam com você: só aparecem se o usuário
perguntar ou se houver ambiguidade que ele precise decidir. Fórmula ou
SQL com `<<ARGUMENTO>>` nunca é apresentado como pronto. Em solução
mista, diga onde cada peça é usada: o SQL roda como relatório ou
consulta (gerador de relatórios, consulta SQL cadastrada); a fórmula é
cadastrada no sistema e roda no cálculo (por funcionário). Se as peças
não se encaixam num uso só, diga isso.
10. **Pedido com dois caminhos: pergunte antes de entregar.** "Listar X e
somar Y" pode ser um relatório só (o valor somado no SQL) ou um cálculo
na folha (fórmula). Pergunte qual o usuário quer. Se for relatório e o
valor vier de uma tabela de movimento que o mapa não prova, isso vira
intenção de schema normal, com JOIN provado, ou lacuna; nunca palpite.
11. **Escada: a menor solução que resolve.** Nível 1 (só funções) antes do 2
(código de cadastro) antes do 3 (fórmula que executa consulta). No nível
3, ofereça primeiro reaproveitar uma consulta já cadastrada (o SQL de
apoio da Stella); só se nenhuma servir, a consulta nova, com a instrução
de cadastro manual: o motor nunca grava no sistema de origem.
12. **Memory Card: procure antes, ofereça depois.** Se a instância tem um
cartão configurado (`egghead/memory_card.json`), antes de escrever um
relatório novo rode `stella.py cartao buscar` e ofereça
reaproveitar o que servir; depois de entregar um relatório aprovado,
ofereça salvar (prévia do `stella.py cartao enviar`; `--confirmar` só
com o "sim"). Salvar já confirma as tabelas do relatório no log de uso.
Uma mudança num relatório salvo pede `--motivo`. O cartão só funciona onde
há o `gh` autenticado e a pasta do cartão (o Claude Code na máquina do
usuário). Fora disso (o claude.ai, por exemplo) não ofereça salvar:
entregue o SQL e o texto do artigo e diga que salvar é pelo Claude Code.
Nunca rode `iniciar` sem o usuário pedir um cartão novo.
13. **Leia os `LEMBRETE:` da saída.** Os comandos imprimem em stderr o
próximo passo que não pode ser esquecido (o `confirmar`, o Memory
Card, a conferência depois de mudar a base). Siga-os.
## Para onde ir
| O pedido envolve | Faça | Detalhe sob demanda |
|---|---|---|
| pedido com vários ingredientes (uma conta + um código de cadastro + uma tabela ou consulta) | quebre o pedido em intenções (JSON) → `stella.py solucionar --intencoes contrato.json` → monte a fórmula só com o que voltou, com `<<ARGUMENTO>>` no código que o usuário preenche → `solucionar` de novo com a `formula` (e o `sql`, se você escreveu um) → entregue como manda a regra 9 | [referencias/fluxo-solucao.md](referencias/fluxo-solucao.md) |
| tabelas/colunas de uma base cadastrada, domínio de negócio (RH, folha, ponto, cadastros), "escreva uma consulta" | `stella.py buscar --dominio schema "<pedido>"` → `detalhar --dominio schema TAB...` (o caminho com o JOIN pronto vem no topo) → escrever o SQL → `confirmar --dominio schema "<pedido>" TAB [TAB ...]` com todas as tabelas usadas | [referencias/fluxo-schema.md](referencias/fluxo-schema.md) |
| criar, corrigir, validar ou explicar uma fórmula de sistema | `stella.py contextos` → `buscar --dominio formulas "<pedido>" --contexto CTX` → `detalhar` → `compor`/`validar` → `explicar` → `confirmar --dominio formulas` | [referencias/fluxo-formulas.md](referencias/fluxo-formulas.md) |
| argumento que é código de um cadastro (evento, cargo, consulta...) | o `detalhar` de fórmulas traz a ligação do parâmetro com a tabela e a coluna e o SQL de apoio para o usuário achar o código; nunca invente o código | [referencias/fluxo-formulas.md](referencias/fluxo-formulas.md), Passo 2 |
| guardar um relatório pronto, versionar uma mudança, procurar um relatório já feito (Memory Card) | antes de escrever um relatório novo: `stella.py cartao buscar`; relatório pronto e aprovado: ofereça salvar, mostre a prévia do `enviar` e só com o "sim" use `--confirmar`; mudança pede `--motivo` e o diff na prévia; sem cartão configurado, aponte para o `iniciar` | [referencias/memory-card.md](referencias/memory-card.md) |
| T-SQL geral (otimizar, depurar, CTE, window, PIVOT/MERGE/APPLY, plano, índice, procedure, .sql) | instruções gerais, convenções e verificação ao vivo | [referencias/tsql.md](referencias/tsql.md) |
| base vazia ou desatualizada, sinônimos, calibração, isolamento | satélites de manutenção (York, Edison, Pythagoras, Lilith, Atlas) | [referencias/nomes.md](referencias/nomes.md) |
Se o pedido for T-SQL genérico sem relação com uma base cadastrada, vá
direto para [referencias/tsql.md](referencias/tsql.md). Se o `status`
disser que a base não está instalada, avise o usuário e aponte para
[referencias/schema.md](referencias/schema.md), seção "Como importar seus
dados", em vez de inventar nomes.
## Referências
- [referencias/fluxo-solucao.md](referencias/fluxo-solucao.md): pedido com várias intenções, contrato JSON, argumento marcado e lacunas
- [referencias/fluxo-schema.md](referencias/fluxo-schema.md) e [referencias/schema.md](referencias/schema.md): descoberta de schema, base Punk Records, import, arquitetura e limitações
- [referencias/fluxo-formulas.md](referencias/fluxo-formulas.md) e [referencias/formulas.md](referencias/formulas.md): fórmulas, dicionário, isolamento público × privado, ingestão
- [referencias/tsql.md](referencias/tsql.md), [patterns.md](referencias/patterns.md), [performance.md](referencias/performance.md), [security.md](referencias/security.md), [data-types.md](referencias/data-types.md), [transactions.md](referencias/transactions.md): T-SQL
- [referencias/memory-card.md](referencias/memory-card.md): cartão de memória dos relatórios (salvar, versionar, buscar, conferir no schema)
- [referencias/nomes.md](referencias/nomes.md): estrutura da skill, papéis e comandos de manutenção
- [referencias/historico.md](referencias/historico.md): histórico de versões e decisões