# Host Studio · Instruções para Auditoria do Motor > **Este documento orienta a IA externa que vai comparar a entrega do motor automático com a entrega manual da equipe Host Studio.** > Use este guia para gerar laudos consistentes. --- ## 1. CONTEXTO A Host Studio gera relatórios de Análise de Viabilidade de duas formas em paralelo durante a fase de afinação do motor: ``` PROPRIEDADE TESTE ↓ ├─→ Entrega manual (equipe humana) │ └─→ Entrega automática (motor de IA) ``` Sua tarefa: comparar as duas entregas usando os CSVs do PriceLabs como verdade dos dados e identificar onde o motor automático difere da entrega humana — classificando cada divergência por tipo. --- ## 2. ARQUIVOS QUE VOCÊ RECEBE NO ZIP ``` auditoria_motor_AAAA-MM-DD.zip ├── 00_instrucoes_auditoria.md ← este arquivo ├── 01_motor_contrato.md ← o que o motor deveria fazer ├── 02_schema_output.md ← schema do JSON esperado (88 campos) ├── 03_glossario_linguagem.md ← regras de tom (sem projeção etc.) ├── inputs/ │ ├── airbnb.csv ← histórico do Airbnb da propriedade │ ├── compset.csv ← Market Dashboard compset │ ├── geral.csv ← Market Dashboard geral │ └── revenue_estimator.csv ← Revenue Estimator do PriceLabs ├── motor_output/ │ ├── relatorio.html ← HTML renderizado pelo motor │ ├── insights.json ← JSON estruturado (88 campos) │ └── logs_execucao.txt ← logs da execução └── host_studio_output/ ├── entrega_manual.pdf ← PDF/análise da equipe └── observacoes_equipe.md ← notas que a equipe quer destacar ``` --- ## 3. PROCESSO DE AUDITORIA ### Passo 1 — Validar os CSVs de input Antes de comparar outputs, confirme que os inputs estão íntegros: ``` [ ] CSV Airbnb tem colunas esperadas (data, valor, noites, ADR) [ ] CSV Compset cobre 24 meses (Mai/24 a Abr/26 ou intervalo equivalente) [ ] CSV Geral cobre o mesmo intervalo do compset [ ] CSV Revenue Estimator tem 12 linhas (uma por mês) [ ] Nenhum CSV está vazio ou malformado ``` Se algum input estiver corrompido, ABORTAR a auditoria e reportar. ### Passo 2 — Calcular dados de referência diretamente dos CSVs Calcule os números que devem aparecer em qualquer relatório, direto dos CSVs: ```python # Período do Airbnb periodo_inicio = min(date) do airbnb.csv periodo_fim = max(date) do airbnb.csv periodo_meses = diferença em meses # Receita histórica da propriedade receita_total_periodo = sum(valor_liquido) do airbnb.csv # ADR médio histórico adr_medio = mean(adr) do airbnb.csv # Ocupação histórica noites_ocupadas = sum(noites) do airbnb.csv ocupacao = noites_ocupadas / (periodo_meses * 30) # Compset filtrado pelo mesmo período compset_filtrado = compset.csv onde mes >= periodo_inicio e mes <= periodo_fim # Médias do compset no período adr_compset_periodo = mean(adr) do compset_filtrado ocupacao_compset_periodo = mean(ocupacao) do compset_filtrado # Deltas reais (mesmo período) delta_adr = (adr_medio - adr_compset_periodo) / adr_compset_periodo delta_ocupacao = (ocupacao - ocupacao_compset_periodo) / ocupacao_compset_periodo # Previsão (Revenue Estimator) receita_anual_p25 = sum(Revenue_25) do revenue_estimator.csv receita_anual_p50 = sum(Revenue_50) receita_anual_p75 = sum(Revenue_75) receita_anual_p90 = sum(Revenue90Percentile) adr_medio_previsao = mean(ADR_50, ignoreZeros=True) ocupacao_previsao = mean(AvgOccupancy) ``` Essa é a **verdade dos dados** contra a qual comparar ambas as entregas. ### Passo 3 — Validar números do motor Compare cada KPI numérico do `insights.json` com os calculados no passo 2: ``` KPI Esperado Motor Diferença ───────────────────────────────────────────────────────────────────────── receita.faturamento_total R$XX.XXX R$XX.XXX ±0,5% mercado.adr_medio R$XXX R$XXX ±0,5% mercado.ocupacao_media XX,X% XX,X% ±0,5% delta.adr +X,X% +X,X% ±0,5% previsao.receita_anual_p50 R$XXX.XXX R$XXX.XXX ±1% ... ``` Tolerância: ±0,5% para a maioria, ±1% para somas grandes (arredondamento). Se diferença for maior, classificar como `[Código]` (bug de cálculo). ### Passo 4 — Validar números da entrega manual Mesma checagem do passo 3, mas comparando com o que a equipe entregou no PDF. Se a equipe humana errou um cálculo, anotar — mas o motor não precisa replicar o erro. ### Passo 5 — Comparar narrativa qualitativa Para cada um dos 12 cards de insight (9 insights + 3 previsão), comparar: ``` INSIGHT: pontos_fortes Motor disse: "[texto do motor]" Host disse: "[texto da equipe]" Análise: ✓ Convergência: ambos mencionam X, Y ⚠ Motor não viu: Z (algo que a equipe identificou e o motor não) 🆕 Motor viu: W (algo novo que pode ser adicionado à entrega manual) ⚠ Tom/linguagem: motor usa termo proibido "projetado" (ver glossário) ``` ### Passo 6 — Validar linguagem Verificar `motor_output/relatorio.html` contra as regras do glossário: ``` PALAVRAS PROIBIDAS (não devem aparecer fora da aba Previsão): - "projetado", "projeção" - "potencial" - "vai render", "vai dar" - "garantia", "garantido" - "estimativa de receita futura" TERMOS TÉCNICOS NÃO TRADUZIDOS (devem ser convertidos): - "ADR" → "diária média" - "RevPAR" → "receita por noite disponível" - "Compset" → "imóveis similares" - "Booking window" → "antecedência de reserva" - "Percentil 75" → "imóveis com melhor desempenho" ``` Se encontrar essas palavras, classificar como `[Motor]` (ajuste no prompt). ### Passo 7 — Validar consistência de período Checagem crítica: o motor filtrou o compset para o mesmo período do Airbnb? ``` periodo_airbnb = motor_output → output.periodo.inicio / fim Para todo delta no relatório: Se delta.usou_compset_filtrado_pelo_periodo == false → BUG CRÍTICO [Código]: motor não normalizou período ``` Se sem filtro, deltas ficam distorcidos (ex: +19% falso vs +3% real). --- ## 4. ESTRUTURA DO LAUDO DE SAÍDA Retornar laudo no seguinte formato: ```markdown # Laudo de Auditoria — Propriedade [Nome] **Data:** 2026-05-16 **Versão do motor:** 2.3.5 --- ## 1. Validação de Inputs ✓ CSVs íntegros, período: Mai/24 a Abr/26 (24 meses) ✓ Revenue Estimator com 12 linhas ✓ Briefing preenchido (85% dos campos) ## 2. Validação de Cálculos | KPI | Esperado | Motor | Host | Status | |---------------------------|----------|-------|-------|--------| | Receita histórica | R$45.3k | R$45.3k | R$45.2k | ✓ | | ADR médio propriedade | R$854 | R$854 | R$850 | ✓ | | Delta ADR vs compset | +3,2% | +18,9%| +3,5% | ✗ [Código] | **Achado crítico:** Motor calculou delta ADR sem filtrar período. Esperado +3,2%, motor reportou +18,9%. ## 3. Validação de Narrativa ### Resumo Executivo - Convergência: 80% - Motor cobriu: posicionamento, sazonalidade - Motor não viu: oportunidade de aumento de ADR em dezembro (Host identificou) ### Pontos Fortes [...] ### [...todos os 12 cards...] ## 4. Linguagem ⚠ Encontrado "projetado" 2x na aba Insights (fora da Previsão) - Card "Conclusão": "...projetado para crescer 15%..." - Recomendação: substituir por "histórico mostra crescimento de" ⚠ Termo "ADR" não traduzido em "Resumo Executivo" - Recomendação: usar "diária média" ## 5. Classificação das Divergências ### [ Motor ] — ajustar prompt/regras na interface - Card "Pontos Fortes": IA não cruzou briefing com compset.desejaveis - Linguagem: substituir termos técnicos - Tom da conclusão: muito formal, ajustar prompt ### [ Motor + Código ] — ajuste duplo - Cálculo de delta ADR sem filtro de período → Código: garantir que `normalize_period` é chamado antes → Prompt: explicar para IA que delta deve usar valores normalizados ### [ Código ] — bug puro - Receita acumulada arredondando incorretamente em meses zerados ### [ Adicionar à instrução ] — IA não tem como saber sem orientação - Considerar dia da semana de feriados nacionais - Mencionar quando propriedade tem WiFi acima da média do compset ## 6. Recomendações Priorizadas 1. **CRÍTICO**: corrigir normalize_period no motor (delta ADR distorcido) 2. **ALTO**: substituir termos técnicos não traduzidos 3. **MÉDIO**: melhorar prompt do card Conclusão 4. **BAIXO**: ajuste de arredondamento ## 7. Próximos passos - [ ] Ajustar `calculations/normalize_period.ts` - [ ] Atualizar prompt do card Pontos Fortes em engine_config - [ ] Adicionar regra de feriados ao motor_contrato.md (seção 8) - [ ] Re-rodar auditoria com correções ``` --- ## 5. CRITÉRIOS DE CLASSIFICAÇÃO Use estas regras para classificar cada divergência: ### [ Motor ] - Texto narrativo errado, vago ou genérico - Linguagem inadequada (termo técnico, tom errado) - Insight superficial que poderia ser mais profundo - Falta de cruzamento de dados que o prompt deveria pedir **Solução:** editar prompt em `engine_config` (interface admin) ### [ Motor + Código ] - Cálculo errado E narrativa baseada no cálculo errado - Falta de dado no JSON E texto que precisa desse dado - Comportamento que requer tanto novo dado quanto nova orientação **Solução:** ajustar código E prompt ### [ Código ] - Bug matemático puro - Parser falhou - Integração com API falhou - Lógica de filtro/normalização ausente **Solução:** abrir Cursor com `motor_contrato.md` e ajustar código ### [ Adicionar à instrução ] - IA não tinha como saber daquela regra - Conhecimento de domínio não documentado - Padrão regional/sazonal não previsto **Solução:** atualizar `motor_contrato.md` ou `engine_config.prompt_principal` --- ## 6. CUIDADOS - **Não invente divergência** — se motor e host disseram a mesma coisa de jeito diferente, isso é OK - **Não favoreça host** — equipe também pode errar; valide ambos contra os CSVs - **Sempre cite CSV** — toda afirmação de "esperado" deve poder ser verificada nos CSVs originais - **Tolerância numérica** — ±0,5% para a maioria, ±1% para somas grandes - **Datas** — atenção a fusos horários e formato (DD/MM vs MM/DD) --- ## 7. CHECKLIST FINAL ANTES DE ENTREGAR O LAUDO ``` [ ] Validei integridade dos 4 CSVs [ ] Recalculei todos os KPIs principais [ ] Comparei motor vs host vs CSVs [ ] Verifiquei consistência de período (filtro do compset) [ ] Verifiquei linguagem (termos proibidos) [ ] Classifiquei cada divergência (Motor/Motor+Código/Código/Instrução) [ ] Priorizei recomendações (CRÍTICO/ALTO/MÉDIO/BAIXO) [ ] Sugeri próximos passos acionáveis ``` --- Bom trabalho.