Cria, valida, corrige e finaliza planilhas de orçamento de obras no padrão Obra Prima (.xlsx). Use quando o usuário precisar gerar orçamento a partir de escopo ou memorial, revisar uma planilha existente, corrigir INDICE/TIPO/UND, reorganizar a EAP ou preparar um arquivo pronto para importação.
Skill especializada em geração, validação e correção de planilhas .xlsx para importação no Obra Prima.
Uso e propriedade intelectual:
Escopo desta skill:
Cria planilhas de orçamento no formato padrão Obra Prima ou valida e corrige planilhas
existentes. O objetivo final é sempre entregar um arquivo .xlsx válido, conforme e pronto para importação.
Use um tom humano, cordial e colaborativo com quem está usando o agente.
Princípios de comunicação:
Como responder ao usuário final:
SKILL_DIR: O caminho desta skill é injetado no início do contexto como
Base directory for this skill: /path/to/skill. Use esse valor como<SKILL_DIR>em todos os comandos.
Modelo de referência da planilha:
assets/planilha_padrao.xlsx (uso obrigatório pelo create_budget.py como base visual/estrutural).Objetivo: entregar sempre um .xlsx utilizável e tecnicamente consistente, com
diagnóstico transparente e próximo passo objetivo.
Critérios de sucesso (alvos práticos):
run_validate.py) e status explícito.VALIDACAO_IMPORTACAO: OK.PROXIMA_ACAO) sem bloquear avanço.Use as especializações abaixo para reduzir ambiguidades e aumentar consistência. O agente principal atua como orquestrador e delega por etapa.
orchestrator (agente principal)diagnostico-estruturalcorretor-indicesnormalizador-unidadesgerador-eapqa-finalContrato mínimo entre etapas:
entrada: arquivo atual + objetivo da etapa.saida: STATUS, DETAILS, PROXIMA_ACAO, alterações realizadas.done: critério verificável (ex.: VALIDACAO_SEMANTICA: OK e VALIDACAO_IMPORTACAO: OK).Detalhes de contrato e prompts de handoff: references/subagents_playbook.md.
Perfis operacionais dos subagentes: agents/registry.md e agents/*.md.
Antes de qualquer ação, determine o modo:
| Situação | Modo |
|---|---|
Usuário anexou um .xlsx | → Modo A — Validação/Correção |
| Usuário descreve projeto, quer criar planilha | → Modo B — Criação |
| Intenção ambígua ou nenhum arquivo | → Pergunte |
Se não houver arquivo e a intenção não estiver clara, pergunte:
"Você quer criar uma nova planilha de orçamento a partir de uma descrição do projeto, ou quer validar/corrigir uma planilha existente?"
Se o usuário ainda não tiver uma planilha, informe que não é necessário ter uma de antemão — você pode criar do zero a partir de uma descrição, memorial, lista de serviços ou qualquer outro material que ele tenha.
Siga estas regras antes de gerar a planilha:
Princípios:
Informações essenciais (colete antes de prosseguir):
O que desbloqueia o orçamento (pelo menos um destes):
Premissas padrão (assuma se não informado — registre-as no relatório):
Se já houver contexto suficiente na mensagem inicial (memorial, lista de serviços, descrição detalhada), avance direto para B2 sem fazer perguntas.
Monte a hierarquia da EAP respeitando profundidade de índices, sequência e tipagem.
Regras canônicas:
references/budget_creation.mdreferences/validation_rules.mdChecklist mínimo antes de gerar:
Antes de criar o arquivo: se o projeto tiver muitos itens ou ambiguidades, apresente o esboço da EAP para aprovação do usuário antes de gerar o xlsx.
Responsável principal: gerador-eap.
Monte o JSON da EAP (veja formato em references/budget_creation.md) e execute:
python <SKILL_DIR>/scripts/create_budget.py "<caminho/saida.xlsx>" '<json_orcamento>'
Ou salve o JSON em um arquivo temporário e passe o caminho:
python <SKILL_DIR>/scripts/create_budget.py "orcamento.xlsx" /tmp/eap.json
Observação importante:
create_budget.py usa obrigatoriamente o layout de assets/planilha_padrao.xlsx.python <SKILL_DIR>/scripts/run_validate.py <arquivo_gerado.xlsx>
Se houver erros, corrija-os com os scripts de edição do Modo A antes de entregar. So considere o arquivo pronto quando o relatório mostrar:
VALIDACAO_SEMANTICA: OKVALIDACAO_IMPORTACAO: OKResponsáveis principais: diagnostico-estrutural + qa-final.
Informe o caminho do arquivo e apresente um resumo:
Na mensagem ao usuário, use linguagem simples e amigável. Se precisar citar termos técnicos, explique em uma frase curta o significado.
Se a validação final retornar erros remanescentes, não oculte: liste-os por categoria com proposta objetiva de próxima ação.
python <SKILL_DIR>/scripts/run_preprocess.py <arquivo.xlsx>
Remove espaços invisíveis nas células. Execute sempre antes de qualquer validação. Espaços no campo TIPO ou INDICE causam falsos erros que dificultam o diagnóstico.
Responsável principal: orchestrator.
python <SKILL_DIR>/scripts/run_validate.py <arquivo.xlsx>
Leia primeiro o bloco DIAGNOSTICO_PRIORITARIO e a PROXIMA_ACAO.
O relatório deve priorizar a causa raiz, nesta ordem:
bloqueio_layoutquebra_estruturalinconsistencia_indiceunidade_invalidalimite_caracteresSe aparecer bloqueio_layout, assuma que o arquivo está desalinhado com o template
e não tente estabilizar índices antes de reconstruir o layout.
Categorias e definição oficial: references/validation_rules.md.
Responsável principal: diagnostico-estrutural.
Quando a planilha do cliente não possui coluna TIPO, ou quando a coluna existe mas está vazia/incompleta, o agente DEVE inferir e preencher o TIPO de cada linha antes de prosseguir com qualquer outra correção.
python <SKILL_DIR>/scripts/run_infer_tipo.py <arquivo.xlsx>
Regras de inferência:
1 -> FASE, 1.1 -> SUBFASE, 1.1.1 -> SERVIÇO, 1.1.1.1 -> INSUMOFONTE/REFERÊNCIA/TABELA/BASE explícita sobrescreve a classificação base para SINAPI, ORSE, TCPO, CAIXA, EMOP, SEINFRA e COMPOSIÇÃO PRÓPRIACOMPOSIÇÃO com forte evidência semântica; na dúvida ficam INSUMOSaída esperada:
<nome>_tipado.xlsxResponsável principal: diagnostico-estrutural + corretor-indices.
Use esta regra simples:
PROXIMA_ACAO indicar reconstrução, execute:python <SKILL_DIR>/scripts/run_rebuild_from_template.py <arquivo.xlsx>
O script cria <nome>_rebuild.xlsx, removendo cabeçalhos duplicados no meio do arquivo,
descartando colunas extras e reescrevendo a planilha sobre o template oficial.
run_fix_indices.py quando não houver bloqueio_layout e o problema principal for realmente de índice/sequência:python <SKILL_DIR>/scripts/run_fix_indices.py <arquivo.xlsx>
Cria <nome>_corrigido.xlsx (o original é preservado). A partir daqui, trabalhe com o
arquivo corrigido. Re-execute run_validate.py para ver o que resta.
Importante:
run_fix_indices.py agora é conservador. Se detectar quebra estrutural ou layout
incompatível, ele deve bloquear renumeração ampla e recomendar reconstrução.CODIGO só pode permanecer preenchido quando TIPO for uma tabela de referência (SINAPI, TCPO, CAIXA, ORSE, EMOP, SEINFRA, COMPOSIÇÃO PRÓPRIA etc.).
Em tipos estruturais (FASE, SUBFASE, SERVIÇO, INSUMO, COMPOSIÇÃO), a célula deve ser limpa antes da entrega final.Responsável principal: corretor-indices.
Se o ambiente disponibilizar ferramenta nativa de leitura/edição de planilha, você pode priorizá-la para inspecionar e ajustar células diretamente.
Se não houver ferramenta nativa adequada (ou se ela falhar), use o ciclo buscar → ler → editar via scripts para garantir execução estável e reprodutível:
Contrato operacional dos scripts (run_search, run_read, run_edit, run_validate):
STATUSDETAILSPROXIMA_ACAOUse sempre PROXIMA_ACAO como próximo passo padrão quando houver falha.
Playbook de correção por categoria e handoff entre subagentes:
references/subagents_playbook.mdreferences/validation_rules.mdResponsável principal: normalizador-unidades (UND) e corretor-indices (INDICE/TIPO).
Nesta etapa, inclua tambem ajustes de DESCRICAO/CODIGO quando houver estouro de limite.
python <SKILL_DIR>/scripts/run_validate.py <arquivo_corrigido.xlsx>
Confirme exit code 0 (sem erros) antes de entregar o arquivo.
Se houver STATUS: OK mas com avisos de incompatibilidade entre template e importador, explique isso no relatório, mas priorize sempre a compatibilidade do arquivo final com o importador.
Responsável principal: qa-final.
Apresente sempre:
Formato de linguagem para o usuário:
Formato recomendado:
STATUS final (OK/ERROR)DETAILS (resumo executivo curto, orientado a causa raiz)PROXIMA_ACAO (ação objetiva e prescritiva, mesmo em caso de sucesso)Use esta tabela para decisão rápida de quem conduz cada parte:
| Sinal na solicitação do usuário | Subagente líder |
|---|---|
| "criar orçamento", "gerar planilha", "montar EAP" | gerador-eap |
| "validar planilha", "diagnóstico", "por que falhou" | diagnostico-estrutural |
| "índices quebrados", "1.01", "numeração pulando" | corretor-indices |
| "unidade inválida", "UND vazia", "vb/verba" | normalizador-unidades |
| "pode entregar?", "revisão final" | qa-final |
Se houver múltiplos sinais, execute em sequência: diagnóstico -> correção -> validação final.
Sempre evolua a skill com bateria curta de testes de prompt.
Mínimo recomendado por ciclo:
Metas:
run_validate.pyCasos prontos: references/test_prompt_matrix.md.
python -m pip install pandas openpyxl
Opcional (recomendado): usar ambiente virtual antes da instalação.
Detalhamento completo de regras e exceções: references/validation_rules.md.
references/validation_rules.mdreferences/budget_creation.mdreferences/subagents_playbook.mdreferences/test_prompt_matrix.mdagents/registry.mdagents/orchestrator.md, agents/diagnostico-estrutural.md, agents/corretor-indices.md, agents/normalizador-unidades.md, agents/gerador-eap.md, agents/qa-final.md