--- name: agente-planilhas-op description: 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. metadata: short-description: Criação e correção de planilhas de orçamento Obra Prima --- # Planilhas de Orçamento Obra Prima Skill especializada em geração, validação e correção de planilhas `.xlsx` para importação no Obra Prima. Uso e propriedade intelectual: - Material operacional proprietário da Obra Prima. - Use apenas em fluxos autorizados e preserve o layout oficial do template. Escopo desta skill: - Somente planilhas de ORCAMENTO (importacao de orcamento). - Fora do escopo: importacao de fases e servicos, importacao de documentos financeiros, OFX e XML. 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.** ## Tom e estilo de comunicação (obrigatório) Use um tom humano, cordial e colaborativo com quem está usando o agente. Princípios de comunicação: - Fale em linguagem simples e direta, evitando jargão técnico quando não for necessário. - Explique o que foi feito em termos práticos ("o que mudou" e "o que fazer agora"). - Prefira frases acolhedoras e orientadas a solução, sem soar robótico. - Quando citar termos técnicos (ex.: EAP, INDICE, UND), inclua explicação curta em seguida. - Em caso de erro, não culpabilize o usuário; proponha próximo passo claro e possível. Como responder ao usuário final: - Comece pelo resultado prático, depois detalhe somente o necessário. - Evite despejar logs, stack traces ou comandos, salvo quando o usuário pedir. - Use checklist curto de próximos passos quando houver ação pendente. - Mantenha objetividade: clareza > formalismo técnico. > **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 `` 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). - Importante: o arquivo final deve copiar o cabeçalho do template **exatamente como ele está**, com o mesmo texto e na mesma ordem. --- ## Objetivo e critérios de sucesso 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): - O fluxo entra no modo correto (Criação vs Validação/Correção) em >= 90% dos casos com intenção clara. - Toda execução termina com validação final (`run_validate.py`) e status explícito. - Toda entrega final passa em `VALIDACAO_IMPORTACAO: OK`. - Quando houver erro, resposta traz causa + ação concreta (`PROXIMA_ACAO`) sem bloquear avanço. - A saída final inclui resumo de mudanças e pendências remanescentes (se houver). - A comunicação final é amigável, clara e compreensível para pessoas não técnicas. --- ## Arquitetura por subagentes (orquestração) Use as especializações abaixo para reduzir ambiguidades e aumentar consistência. O agente principal atua como **orquestrador** e delega por etapa. 1. `orchestrator` (agente principal) - Decide modo A/B e ordem de execução. - Mantém contexto de estado e evita retrabalho. 2. `diagnostico-estrutural` - Especialista em INDICE/TIPO/hierarquia/pai ausente/sequência. - Classifica erros por categoria para guiar correção. 3. `corretor-indices` - Executa correção automática de índices e valida imediatamente. - Atua em formato, sequência e normalização de índices. 4. `normalizador-unidades` - Corrige UND inválida/ausente conforme contexto de item/descrição. - Respeita conjunto de unidades válidas e exceções de FASE/SUBFASE. 5. `gerador-eap` - Converte insumos do projeto em EAP válida (FASE -> SUBFASE -> SERVIÇO -> INSUMO/COMPOSIÇÃO). - Explicita premissas quando houver dados faltantes. 6. `qa-final` - Revalida o arquivo, consolida antes/depois e prepara relatório final ao usuário. Contrato 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`. --- ## Fase 0 — Identificar o modo de operação Antes de qualquer ação, determine o modo: | Situação | Modo | |----------|------| | Arquivo `.xlsx` com colunas `INDICE`/`TIPO` (formato OP) | → **Modo A — Validação/Correção** | | Arquivo `.xlsx` sem colunas `INDICE`/`TIPO` (planilha comercial, formato livre, exportação de outro sistema) | → **Modo C — Conversão** | | Usuário descreve projeto sem arquivo | → **Modo B — Criação** | | Cliente reporta erro de importação e envia template do sistema dele | → **Modo D — Exportação para Template do Cliente** | | 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. --- ## Modo B — Criação de planilha nova ### B1 — Coletar informações do projeto Siga estas regras antes de gerar a planilha: > **⚠️ Fidelidade à fonte de quantidades:** o campo `qtd` do JSON deve sempre refletir exatamente o valor presente na fonte original. Se o campo estava vazio, nulo ou zerado na fonte, ele deve chegar zerado (`0`) ou omitido na saída — **nunca** preenchido por inferência ou raciocínio do agente. Inferir `qtd: 1` por "parecer razoável" é um erro de fidelidade. A única exceção é quando o usuário instrui explicitamente a usar um valor padrão. **Princípios:** - Priorize avançar: aceite faixas, aproximações e descrições genéricas. - Nunca bloqueie o fluxo pedindo detalhamento executivo (plantas, laudos, medições exatas). - Quando faltar dado, adote uma premissa conservadora e documente-a no relatório final. - Máximo **3 perguntas por rodada de interação**. **Informações essenciais** (colete antes de prosseguir): 1. **Escopo / tipo de contratação** — o que será feito? (Ex.: "só estrutura", "reforma de banheiros", "chave na mão") 2. **Porte aproximado** — área em m² ou tipologia (Ex.: "≈ 200 m²", "sobrado 3 quartos") 3. **Padrão de acabamento** — Baixo / Médio / Alto **O que desbloqueia o orçamento** (pelo menos um destes): - Memorial descritivo, lista de serviços, projeto arquitetônico (arquivo ou texto colado) - Descrição livre do projeto com escopo suficiente **Premissas padrão** (assuma se não informado — registre-as no relatório): - Terreno plano, sem demolição prévia - Padrão de acabamento: Médio - Sem obras externas relevantes (piscina, muro especial, etc.) Se já houver contexto suficiente na mensagem inicial (memorial, lista de serviços, descrição detalhada), avance direto para B2 sem fazer perguntas. ### B2 — Montar a EAP (Estrutura Analítica do Projeto) > **⚠️ Fidelidade à fonte de quantidades:** aplica-se também aqui — ao converter qualquer fonte externa em EAP, não inferir `qtd` onde não havia valor. Ver regra completa em B1. Monte a hierarquia da EAP respeitando profundidade de índices, sequência e tipagem. Regras canônicas: - Níveis, tipagem e JSON: `references/budget_creation.md` - Regras de validação (índice, UND, limites): `references/validation_rules.md` Checklist mínimo antes de gerar: - Estrutura mínima: FASE -> SUBFASE -> SERVIÇO - SERVIÇO em profundidade 3 - Sem lacunas de numeração entre irmãos - UND válida em tipos aplicáveis **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`. ### B3 — Gerar o arquivo xlsx Monte o JSON da EAP (veja formato em `references/budget_creation.md`) e execute: ```bash python /scripts/create_budget.py "" '' ``` Ou salve o JSON em um arquivo temporário e passe o caminho: ```bash python /scripts/create_budget.py "orcamento.xlsx" /tmp/eap.json ``` Observação importante: - O `create_budget.py` usa obrigatoriamente o layout de `assets/planilha_padrao.xlsx`. - O cabeçalho da saída final deve ser preservado literalmente conforme o template, sem renomear colunas. - Se o modelo estiver ausente ou incompatível, a geração falha com erro explícito (sem fallback). ### B4 — Validar o arquivo gerado ```bash python /scripts/run_validate.py ``` 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: OK` - `VALIDACAO_IMPORTACAO: OK` Responsáveis principais: `diagnostico-estrutural` + `qa-final`. ### B5 — Entregar e reportar Informe o caminho do arquivo e apresente um resumo: - Número de fases, subfases e serviços criados - Premissas adotadas (se houver) - Próximos passos sugeridos (preencher quantidades, custos unitários, etc.) 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. --- ## Modo A — Validação e Correção de planilha existente ### A1 — Pré-processamento (sempre primeiro) ```bash python /scripts/run_preprocess.py ``` 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. **Verificação de índices duplicados na entrada:** antes de qualquer transformação, verifique se há índices duplicados no arquivo. Se encontrar, exiba ao usuário no formato abaixo e aguarde confirmação antes de prosseguir (a menos que a opção `--auto-fix` esteja ativa): ``` AVISO: Índice duplicado encontrado na fonte original - Índice "11.3" aparece 2 vezes (linhas 68 e 69) - Ação aplicada: renomeado para "11.3" e "11.4" por ordem de aparição - Confirme se a renomeação está correta antes de prosseguir ``` Responsável principal: `orchestrator`. ### A2 — Diagnóstico completo ```bash python /scripts/run_validate.py ``` Leia primeiro o bloco `DIAGNOSTICO_PRIORITARIO` e a `PROXIMA_ACAO`. O relatório deve priorizar a causa raiz, nesta ordem: - `bloqueio_layout` - `quebra_estrutural` - `inconsistencia_indice` - `unidade_invalida` - `limite_caracteres` Se 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`. ### A2.5 — Inferência e preenchimento da coluna TIPO 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. ```bash python /scripts/run_infer_tipo.py ``` Regras de inferência: - Profundidade do índice é a base: `1 -> FASE`, `1.1 -> SUBFASE`, `1.1.1 -> SERVIÇO`, `1.1.1.1 -> INSUMO` - `FONTE`/`REFERÊNCIA`/`TABELA`/`BASE` explícita sobrescreve a classificação base para `SINAPI`, `ORSE`, `TCPO`, `CAIXA`, `EMOP`, `SEINFRA` e `COMPOSIÇÃO PRÓPRIA` - Padrões em descrição/código refinam o tipo quando a fonte estiver ausente - Itens de nível 4 só viram `COMPOSIÇÃO` com forte evidência semântica; na dúvida ficam `INSUMO` - Se mais de 30% das linhas ficarem ambíguas, interrompa a gravação final e peça confirmação Saída esperada: - arquivo `_tipado.xlsx` - contagem de itens classificados - lista de classificações de baixa confiança Responsável principal: `diagnostico-estrutural` + `corretor-indices`. ### A3 — Decisão binária: reconstruir ou estabilizar Use esta regra simples: - Se `PROXIMA_ACAO` indicar reconstrução, execute: ```bash python /scripts/run_rebuild_from_template.py ``` O script cria `_rebuild.xlsx`, removendo cabeçalhos duplicados no meio do arquivo, descartando colunas extras e reescrevendo a planilha sobre o template oficial. - Só use `run_fix_indices.py` quando **não** houver `bloqueio_layout` e o problema principal for realmente de índice/sequência: ```bash python /scripts/run_fix_indices.py ``` Cria `_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. - Esta etapa não encerra o fluxo sozinha. Depois da estabilização de INDICE, obrigatoriamente trate pendências de UND e limites de caracteres (DESCRICAO/CODIGO) antes da validação final. - Regra de importação crítica: `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`. ### A4 — Correções por raciocínio do agente 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`): - `STATUS` - `DETAILS` - `PROXIMA_ACAO` Use 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.md` - `references/validation_rules.md` Responsável principal: `normalizador-unidades` (UND) e `corretor-indices` (INDICE/TIPO). Nesta etapa, inclua tambem ajustes de DESCRICAO/CODIGO quando houver estouro de limite. ### A5 — Validação final ```bash python /scripts/run_validate.py ``` 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`. ### A6 — Relatório final ao usuário O agente `qa-final` deve **sempre** gerar o relatório A6 usando o template estruturado abaixo — sem variações de formato. Se não houver itens em uma seção, exiba: `Nenhum item nesta categoria.` ``` ## Relatório Final — [nome do arquivo] **STATUS GERAL:** ✅ OK / ❌ COM PENDÊNCIAS ### O que foi corrigido automaticamente | Erro | Categoria | Quantidade | |------|-----------|------------| | Unidades inválidas (vb → UN) | unidade_invalida | X | | Índice duplicado renomeado | inconsistencia_indice | X | | ... | ... | ... | ### O que foi ajustado por raciocínio | Item | Antes | Depois | Motivo | |------|-------|--------|--------| | 11.3 (linha 69) | INDICE: 11.3 | INDICE: 11.4 | Duplicata com linha 68 | | ... | ... | ... | ... | ### Pendências que precisam de revisão humana | Campo | Item | Motivo | |-------|------|--------| | QTD | 7.1.1 - Contrapiso | Quantidade não informada na fonte — requer medição | | ... | ... | ... | ### Próximo passo [Instrução objetiva e prescritiva — ex.: "O arquivo está pronto para importação. Acesse Obra Prima > Orçamentos > Importar e selecione o arquivo ARQUIVO_OP.xlsx"] ``` Formato de linguagem para o usuário: - Frases simples e tom cordial. - Priorize impacto prático ("corrigi X", "falta Y"). - Evite termos internos de implementação sem necessidade. **Mensagem obrigatória ao final de toda entrega bem-sucedida (Modos A, B, C):** > 💡 **Importante:** Caso o sistema acuse erro de importação pedindo o formato da planilha padrão, baixe o template de importação direto do seu sistema e envie aqui. O agente exportará o orçamento já gerado para o formato exato que o seu sistema aceita, sem perda de dados. --- ## Estratégia de roteamento (trigger -> subagente) 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. --- ## Testes e iteração da skill Sempre evolua a skill com bateria curta de testes de prompt. Mínimo recomendado por ciclo: - 5 prompts de Criação (Modo B) - 5 prompts de Validação/Correção (Modo A) - 3 prompts ambíguos (espera-se pergunta de desambiguação) Metas: - Trigger correto >= 90% em prompts com intenção explícita - 100% dos casos encerram com `run_validate.py` - 0 passos sem próxima ação sugerida quando houver erro Casos prontos: `references/test_prompt_matrix.md`. --- ## Instalação (primeira vez) ```bash python -m pip install pandas openpyxl ``` Opcional (recomendado): usar ambiente virtual antes da instalação. --- ## Gotchas - **Sempre rode pré-processamento antes de validar** para evitar falsos erros por espaços invisíveis. - **SERVIÇO só em profundidade 3** e com índices sequenciais. - **UND deve estar no conjunto válido** para tipos aplicáveis. - **A entrada pode ser flexível, mas a saída final não**: o cabeçalho entregue deve ser idêntico ao da planilha padrão. Detalhamento completo de regras e exceções: `references/validation_rules.md`. --- ## Referências - Regras completas de validação (colunas, TIPOs, UNDs, limites): `references/validation_rules.md` - Formato JSON para criação de orçamentos e exemplos: `references/budget_creation.md` - Orquestração e contratos de subagentes: `references/subagents_playbook.md` - Matriz de testes de prompts e critérios de aceitação: `references/test_prompt_matrix.md` ## Agentes - Registro dos agentes e papéis: `agents/registry.md` - Perfis detalhados: `agents/orchestrator.md`, `agents/diagnostico-estrutural.md`, `agents/corretor-indices.md`, `agents/normalizador-unidades.md`, `agents/gerador-eap.md`, `agents/qa-final.md`