19970836597/-agent

Gerente de Projetos Imobiliários · Apresentação de Análise de Desempenho Mensal PPT

O núcleo não é "colocar os dados no slide", mas sim explicar claramente a base operacional na ordem cognitiva do público e, em seguida, localizar as causas anômalas com responsáveis e prazos.

---

O conhecimento desta skill está armazenado em dois lugares

Arquivo	Para quem	O que contém
SKILL.md (este arquivo)	Pessoa / Agente	Por que apresentar assim: razão narrativa, método de atribuição de causas, disciplina de expressão
deck_spec.json	Ferramenta	Como implementar: número de páginas, ordem, modelos de frases conclusivas, paleta de cores

deck_spec.json é o conhecimento legível por máquina desta skill. Alterá-lo ajusta o número de páginas e a forma de apresentação do PPT, sem precisar modificar nenhum código Python:

{
  "page_rules": [                       // ← "quantas páginas o ppt terá" está aqui
    {"max_minutes": 10, "sections": [7 parágrafos]},
    {"max_minutes": 20, "sections": [11 parágrafos]},
    {"max_minutes": 40, "sections": [16 parágrafos]}
  ],
  "sections": [{
    "key": "revenue", "label": "Receita", "layout": "chart",
    "data": {"value_column": "Valor da Fatura (R$)", "group_column": "Item de Cobrança"},
    "narrative": [                      // ← Modelo de frase conclusiva: de "ler números" a "dar um julgamento"
      {"when": "top_share > 0.9",
       "so_what": "{top_name} representa {top_share_pct}% da receita, estrutura única, baixa capacidade de resistência a riscos; no próximo mês, focar na receita de áreas comuns como item especial."},
      {"when": "", "so_what": "…cláusula padrão…"}
    ]
  }],
  "theme": {"colors": {...}, "palette": [...]}   // ← Paleta de cores também é conhecimento
}

Como funcionam os modelos de frases conclusivas

O mecanismo seleciona a primeira correspondência da lista de modelos com base na condição when e preenche {placeholders} com números reais.

Placeholders disponíveis (calculados automaticamente a partir dos dados): {total} {count} {top_name} {top_share} {top_share_pct} {group_count} {bottom_name} {bottom_value} …

Sufixos de formatação: {total:mil} (÷1000) {share:pct} (razão → porcentagem) {count:sep} (separador de milhares) {value:2} (casas decimais)

Condições suportadas: > >= < <= == !=, and/or/not, has(x)/empty(x). Condições não analisáveis são consideradas como não correspondentes, sem gerar erro.

Na ausência de dados, rebaixamento honesto: o título da página marca "Dados ausentes, aguardando complemento", nunca usando outra coluna como substituta. Por exemplo, se a página de "Custos" declara a coluna Item de Custo, mas ela não existe nos dados, a página indica explicitamente o que está faltando.

Indicadores devem ser calculados a partir dos dados, não transmitidos manualmente

A seção derived declara "como calcular", e a ferramenta realiza o cálculo:

"derived": {
  "Valor Recebido (R$)": {"expr": "Valor da Fatura (R$) - Valor Não Pago (R$)"},          // linha por linha, torna-se nova coluna
  "Taxa de Arrecadação": {"expr": "Valor Recebido (R$) / Valor da Fatura (R$) * 100",
             "scope": "total", "format": "{:.2f}%"}                  // calcula **um único número** com base no total
}

⚠ O scope padrão é row (calcula linha por linha, resultado torna-se nova coluna); indicadores de razão devem usar obrigatoriamente scope: "total" — calcular a razão linha por linha e depois somar resultaria em valores absurdos como 1.476.800%.

Os valores calculados são automaticamente incorporados à tabela de fatos narrativos, então {Taxa de Arrecadação} pode ser usada diretamente nos modelos de frases conclusivas.

Verificação empírica (2、Informações de Recebíveis.xlsx): Taxa de Arrecadação = 92,48%, Taxa de Inadimplência = 7,52%. Verificação independente agrupando por "Status de Pagamento" confirma total consistência (soma de valores não pagos em linhas pagas = 0).

Expressões só podem referenciar nomes de colunas e constantes numéricas, usando uma lista branca de ast para avaliação — não usa eval. __import__('os') e similares serão rejeitados.

Somente quando as dimensões não existem na tabela principal é necessário fazer JOIN entre tabelas

datasets + join declara "qual tabela usar, quais colunas pegar, por qual chave":

"datasets": {
  "properties": {"file": "1、Informações de Clientes Imobiliários.xlsx", "key_column": "Código do Imóvel",
                 "pick": {"Área de Cobrança Medida (m²)": "Área de Cobrança Medida"}}
},
"join": {"dataset": "properties", "left_on": "Nome Completo do Imóvel", "how": "left"}

Ordem: primeiro o JOIN, depois os cálculos derivados — caso contrário, as colunas de dimensão referenciadas nas expressões derivadas ainda não existirão.

Lição: Primeiro meça, depois decida se precisa de JOIN. Originalmente pensei que "a taxa de arrecadação precisaria de JOIN entre tabelas", mas depois de medir descobri que a Tabela 2 já contém tanto o valor da fatura quanto o valor não pago, portanto pode ser calculada com uma única tabela. O que realmente precisou de JOIN foi o "preço médio unitário" (a área está na Tabela 1).

---

É obrigatório entregar três itens

Entrega	Forma	Função
① PPTX do Relatório	Apresentação editável 16:9	Slides, para "ver"
② Relatório de Verificação checks.json	JSON (produzido pela ferramenta pptx_check)	Evidência de integridade estrutural
③ Script de Apresentação	Corpo do chat / Markdown (modelo em references/03-模型deApresentação.md)	Texto palavra por palavra, para "falar"

Quando usar

• Análise de desempenho mensal/trimestral de projeto imobiliário PPT
• Relatório de desempenho para centro de operações regional, diretor geral
• Necessidade de atribuição de estouro de custos, análise de taxa de arrecadação, análise de eficiência per capita
• Palavras-chave: "Relatório mensal do gerente de projeto" "Material para reunião de análise de desempenho" "PPT de painel de desempenho do projeto"

---

Pipeline de Processamento de Cinco Estágios

Entrada de dados do usuário
      |
      v
+-------------------+
| Estágio 1: Compreensão de Dados |  Analisar entrada, preencher valores padrão, verificar critérios
+-------------------+
      |
      v
+-------------------+
| Estágio 2: Análise de Dados   |  Cálculo de receita/custo/arrecadação/eficiência, classificação de desvios, atribuição de anomalias
+-------------------+
      |
      v
+-------------------+
| Estágio 3: Planejamento da Estrutura PPT |  Definir número de páginas, tipo de gráfico, título conclusivo de cada página
+-------------------+
      |
      v
+-------------------+
| Estágio 4: Geração de Conteúdo   |  Construir dicionário DATA, gerar frases conclusivas, preencher scripts
+-------------------+
      |
      v
+-------------------+
| Estágio 5: Chamar Ferramenta PPT|  Executar build_deck.py → Verificar → Entregar
+-------------------+
      |
      v
Gerar .pptx + checks.json + Script de Apresentação

---

Estágio 1: Compreensão de Dados

1.0 De onde vêm os dados (três caminhos, por prioridade)

Prioridade	Forma	Descrição
1	O usuário forneceu os dados na conversa	O agente preenche os dados no parâmetro data
2	O usuário forneceu o nome do arquivo/pista	A skill automaticamente procura arquivos em diretórios comuns e extrai dados (veja abaixo)
3	Nenhum dos anteriores	Usa o modelo padrão para gerar e emite um aviso de dados insuficientes

Extração automática de dados: Quando data está vazio, a skill:

1. Analisa pistas do nome do arquivo a partir de request (ex.: "a tabela de vendas do mês passado")
2. Faz correspondência difusa nos diretórios data/common e data/inbox
3. Lê com pandas, inferindo automaticamente a coluna de data / coluna de valor / coluna de agrupamento
4. Converte para a estrutura contratual (valor ÷ 1000 para milhares, razões em formato decimal)
5. Salva como input_data.json para o script de geração

Portanto, o usuário só precisa dizer "faça uma apresentação de análise de desempenho usando a tabela de vendas do mês passado", sem fornecer o caminho — desde que o arquivo já esteja em data/common.

Raiz de pesquisa coberta: SKILL_COMMON_DIRS=D:\Planilhas;E:\RelatoriosMensais Desligar extração automática: auto_resolve_data=False

Fontes de dados do projeto imobiliário (critérios medidos em data/common)

Tabela	Arquivo	Uso	Descrição do Critério
Tabela 2	2、Informações de Recebíveis.xlsx	Tabela principal (15.876 linhas)	Receita agrupada por "Item de Cobrança"; "Valor da Fatura / Valor Não Pago" deriva a taxa de arrecadação (medido 92,48%)
Tabela 1	1、Informações de Clientes Imobiliários.xlsx	Tabela de dimensão: Área de Cobrança Medida	JOIN por "Código do Imóvel" = Nome Completo do Imóvel da tabela principal → deriva preço médio unitário (medido 0,30 R$/m²·período)
Tabela 4	4、Relatório Detalhado de Inadimplência.xlsx	Tabela de dimensão: Motivo da Inadimplência (7 categorias)	Título na 2ª linha (header_row=1), com linha de total no final (descartada automaticamente); JOIN por "Nome Completo do Imóvel" → Página de atribuição de inadimplência
Tabela 5	5、Tabela Detalhada de Taxa de Arrecadação por Imóvel.xlsx	Não usar	Cabeçalho composto de três linhas, formato de tabela larga, propenso a conflito com os critérios derivados da Tabela 2; sempre usar os critérios derivados da Tabela 2 como padrão

Declaração de rebaixamento honesto: Os dados deste projeto não contêm dados de custos, orçamento, número de funcionários ou ordens de serviço. A página de custos já foi substituída pela página de "Inadimplência e Cobrança" (com dados reais utilizáveis), e a página de eficiência mantém apenas o "preço médio unitário" com suporte de dados. Os dados de antiguidade de quatro camadas não estão na Tabela 2 — quando necessários, o agente principal deve primeiro chamar o subagente de cobrança (arrears_analysis) para análise de antiguidade e depois injetar os resultados como extra_facts nesta skill.

1.1 Analisar entrada do usuário → Extrair informações básicas

Elemento	Padrão/Exemplo	Descrição
Nome do Projeto	XX Condomínio	Obrigatório, se faltar marca "A ser complementado"
Período do Relatório	Este mês	Obrigatório
Unidade Monetária	Milhares de reais	Uniforme em todo o documento, não misturar; se os dados originais estiverem em "reais", deve-se dividir por 1000
Critério da Razão	Decimal	0,952 = 95,2%; enviar 95,2 será renderizado como 9520%
Base de Comparação	Orçamento mensal + Mês anterior	Pelo menos um quadro de referência
Duração do Relatório	20 minutos	Determina o número de páginas

1.2 Verificação de Integridade dos Dados — Sete grupos de dados obrigatórios

Verifique se o usuário forneceu os sete grupos de dados a seguir; se algum grupo faltar, marque "A ser complementado" na página correspondente:

#	Grupo de Dados	Campos específicos
1	Receita por item	Taxa de condomínio, Receita de áreas comuns, Operações diversas, Outros (Valor real + Valor orçado)
2	Custos por item	Pessoal, Energia de áreas comuns, Terceirização, Manutenção, Materiais, Taxas administrativas (Valor real + Valor orçado)
3	Dados de Arrecadação	A receber do mês / Recebido no mês / Inadimplência inicial do período / Recuperação de inadimplência antiga
4	Antiguidade da Inadimplência	Saldo devedor: 0-30 / 31-90 / 91-180 / 180+ dias
5	Dados de Eficiência	Número de funcionários, Área sob gestão, Volume de ordens de serviço, Custo de pessoal
6	Itens Anômalos	3 a 5 itens com maior desvio e seus eventos rastreáveis
7	Ações do Mês Anterior	Status de conclusão (obrigatório reportar, formando um ciclo fechado)

1.3 Verificação de Critérios de Dados

Antes de entrar na análise, deve-se verificar os seguintes pontos vermelhos nos critérios de dados:

• Receita de áreas comuns pertence legalmente a todos os condôminos, deve ser listada separadamente, não podendo ser incluída no lucro operacional
• Taxa de arrecadação do período denominador = valor total das faturas a receber do mês, não deve incluir recuperação de inadimplência antiga
• Custos de pessoal devem incluir obrigatoriamente INSS, FGTS, horas extras, mão de obra terceirizada convertida
• Energia deve distinguir "rateio de áreas comuns" de "uso próprio da administradora"
• Despesas não recorrentes (reparos emergenciais, grandes reparos) devem ser listadas separadamente, não entrando na base comparável mensal
• Eficiência per capita deve ser avaliada em conjunto com a taxa de custo de mão de obra, não apenas com a variação do número de funcionários

---

Estágio 2: Análise de Dados

2.1 Ordem de Análise (deve ser seguida rigorosamente, não alterar)

Análise de Receita → Análise de Custos → Análise de Taxa de Arrecadação → Análise de Eficiência Per Capita → Atribuição de Itens Anômalos

Razão da ordem: A taxa de arrecadação é a consequência da qualidade do serviço (reclamação não resolvida → proprietário se recusa a pagar), colocar após receita e custos faz a causalidade ser válida; a atribuição de anomalias deve ser baseada nos quatro pilares operacionais, caso contrário a discussão perderá o foco.

2.2 Análise de Receita

• Calcular o desvio real vs. orçado para cada item de receita
• Calcular a taxa de cumprimento do orçamento = Receita reconhecida no mês / Receita orçada no mês
• Calcular a participação percentual da estrutura de receita
• Receita de áreas comuns listada separadamente, com anotação "Pertence a todos os condôminos, não incluída no lucro operacional"

2.3 Análise de Atribuição de Inadimplência (Originalmente Análise de Custos, este projeto não tem dados de custos)

Os dados deste projeto não possuem conta de custos, esta seção foi alterada para atribuição de inadimplência por motivo — uma página que, na gestão imobiliária, impacta o fluxo de caixa tanto quanto os custos:

• Usar a coluna "Valor Não Pago (R$)" da tabela principal, agregada pelos motivos de inadimplência obtidos via JOIN (medido total de R$ 36.400,00, conferido com o Relatório Detalhado de Inadimplência por unidade)
• ⚠ Não usar a coluna "Valor Total da Dívida (R$)" obtida via JOIN para agregação — ela é o total por unidade, que seria duplicado se houver múltiplas linhas de fatura para a mesma unidade
• Os quatro estratos de motivo de inadimplência são pareados com estratégias de cobrança: Disputa de serviço (primeiro corrigir, depois cobrar) / Dificuldade objetiva (plano de parcelamento) / Inadimplência maliciosa (carta formal, escalonamento) / Perda de contato ou imóvel vago (verificação presencial)
• Quando os dados de custos estiverem disponíveis, basta substituir a seção arrears do deck_spec.json pela seção cost, sem alterar a cadeia de ferramentas

2.4 Análise de Taxa de Arrecadação — Decomposição em três níveis

Indicador	Critério de Cálculo
Taxa de Arrecadação do Período	Recebido no mês / A receber no mês (excluindo recuperação de inadimplência antiga)
Taxa de Arrecadação Acumulada	Recebido do início do ano até agora / A receber do início do ano até agora
Taxa de Recuperação de Inadimplência Antiga	Inadimplência histórica recuperada no período / Total de inadimplência antiga no início do período

Em conjunto com a pirâmide de antiguidade: 0-30 / 31-90 / 91-180 / 180+ dias. Quanto maior a antiguidade, menor a probabilidade de recuperação (acima de 180 dias, apenas 10%~20%).

Estratos de motivo de inadimplência: Disputa de serviço / Dificuldade objetiva / Inadimplência maliciosa / Perda de contato ou imóvel vago. As duas primeiras categorias dependem de recuperação do serviço, as duas últimas, de mecanismos de cobrança.

2.5 Análise de Eficiência Per Capita

Indicador	Critério de Cálculo
Área média por pessoa	Área construída sob gestão ÷ (Funcionários próprios + mão de obra terceirizada convertida)
Produtividade por pessoa	Receita operacional ÷ Número total de funcionários do projeto
Volume de ordens de serviço por pessoa	Número de ordens concluídas ÷ Número de funcionários de manutenção
Taxa de custo de mão de obra	Custo de pessoal ÷ Receita operacional (indicador inverso, quanto menor, melhor)

⚠ Armadilha: Substituir funcionários próprios por terceirizados reduz o denominador e melhora os números, deve ser avaliado em conjunto com a taxa de custo de mão de obra.

2.6 Atribuição de Itens Anômalos — Método de Penetração em Três Camadas

Este é o passo mais valioso de toda a análise.

Camada	Pergunta a responder	Saída
Primeira camada: Quantificar desvio	É desvio de volume, preço ou critério?	Valor do desvio + Taxa de desvio
Segunda camada: Fatores de direcionamento	Detalhar até rastrear evento específico	Descrição de evento verificável
Terceira camada: Atribuição de responsabilidade	Controlável / Parcialmente controlável / Incontrolável, quem é o principal responsável	Departamento responsável + Ação corretiva + Prazo

Exemplo de decomposição de desvio de custo de pessoal:

Desvio = Desvio de número de funcionários × Salário médio orçado (desvio de volume)
       + Número orçado de funcionários × Desvio de salário médio (desvio de preço)
       + Fatores de critério / não recorrentes (desvio de critério)

Norma de redação:

• ❌ "Aumento no consumo de energia" → ✅ "Estouro de energia em R$ 21.000,00, atraso na reforma da iluminação do subsolo resultou no uso de lâmpadas antigas durante todo o mês (R$ 12.000,00) + 3 elevadores com teste de funcionamento anual prolongado (R$ 9.000,00)"
• ❌ "Estouro em despesas de manutenção" → ✅ "Estouro em despesas de manutenção de R$ 13.000,00, reparo emergencial de tubulação de esgoto rompida no Bloco 5, R$ 13.000,00 (incontrolável)"

Atribuição sem responsável e prazo equivale a não atribuir.

---

Estágio 3: Planejamento da Estrutura PPT

3.1 Ordem de Apresentação (seis seções, não alterar)

① Conclusão em uma página (decisão em 30 segundos)
② Receita: de onde vem o dinheiro       → Taxa de condomínio / Receita de áreas comuns / Operações diversas / Outros
③ Inadimplência e Cobrança: quem está devendo → Quatro estratos de motivo: Disputa de serviço / Dificuldade / Malícia / Perda de contato
④ Taxa de Arrecadação: o dinheiro foi recebido?   → Período / Acumulado / Inadimplência antiga / Antiguidade por estratos
⑤ Eficiência Per Capita: o custo do pessoal vale a pena   → Preço médio unitário / Área por pessoa / Taxa de custo de mão de obra / Ordens por pessoa
⑥ Atribuição de Itens Anômalos         → Penetração em três camadas: Quantificar desvio → Evento motor → Responsabilidade e controlabilidade
⑦ Resumo e Ações         → 3 a 5 itens, cada um com responsável + prazo + critério de aceitação quantificado

3.2 Planejamento do Número de Páginas

Duração	Páginas Sugeridas	Tratamento da Estrutura
10 minutos	6 a 8 páginas	Conclusão em uma página + Receita e Custos + Anomalias TOP3 + Ações
20 minutos	12 a 16 páginas	Seis seções completas, atribuição de anomalias com TOP5
40 minutos	20 a 28 páginas	Adicionar comparação de tendências (3 a 6 meses), benchmarking com pares, aprofundamento em itens específicos

3.3 Escolha de Gráficos

Conteúdo da Análise	Tipo de Gráfico
Receita real vs. orçada	Gráfico de colunas de duas séries
Classificação de desvios de custos	Gráfico de barras (cores semânticas vermelho/amarelo/verde)
Taxa de Arrecadação + Antiguidade	Gráfico de colunas em camadas + Cartões de indicadores de três níveis
Tendência de eficiência per capita	Gráfico combinado de colunas + linhas (eixo secundário mostrando taxa de custo)
Atribuição de anomalias	Gráfico de barras + Tabela de atribuição
Ações	Cartões de ação (Responsável / Prazo / Critério de Aceitação)

3.4 Modelo de Estrutura de Cada Página

┌──────────────────────────────┐
│ Cabeçalho: Nº + Título conclusivo + Rótulo da seção │
├──────────────────────────────┤
│                              │
│    Área de gráfico / visualização de dados       │
│                              │
├──────────────────────────────┤
│ Barra de conclusão: Frase conclusiva so_what         │
├──────────────────────────────┤
│ Rodapé: Descrição do critério                 │
└──────────────────────────────┘

---

Estágio 4: Geração de Conteúdo

4.1 Construir Dicionário DATA

Com base nos resultados da análise do Estágio 2, preencher os dados no dicionário DATA padronizado.

DATA = {
    "Projeto": "<Nome do Projeto>",
    "Período": "<AAAA Mês M>",
    "Receita": {"Taxa de condomínio": 0, "Receita de áreas comuns": 0, "Operações diversas": 0, "Outros": 0},
    "Orçamento de Receita": {...},
    "Custos": {"Custos de pessoal": 0, "Energia de áreas comuns": 0, "Serviços terceirizados": 0, "Manutenção e reparos": 0, "Materiais e suprimentos": 0, "Taxas administrativas e outros": 0},
    "Orçamento de Custos": {...},
    "Arrecadação": {"A receber do mês": 0, "Recebido no mês": 0, "Inadimplência inicial do período": 0, "Recuperação de inadimplência antiga": 0},
    "Antiguidade": {"0-30 dias": 0, "31-90 dias": 0, "91-180 dias": 0, "Acima de 180 dias": 0},
    "Eficiência": {"Área média por pessoa": 0, "Produtividade por pessoa": 0, "Taxa de custo de mão de obra": 0, "Ordens de serviço por pessoa": 0},
    "Meses de tendência": [...],
    "Tendência de receita": [...],
    "Tendência de custos": [...],
    "Taxa de cumprimento do orçamento": 0,
    "Taxa de custos": 0,
    "Taxa de custos orçada": 0,
    "Conclusão do mês": "<Resumo em três frases: resultado operacional + maior anomalia + primeira ação do próximo mês>",
    "Maior anomalia": "<Item e valor com maior desvio>",
    "Primeira ação": "<Ação de maior prioridade para o próximo mês>",
}

4.2 Gerar Frases Conclusivas para Cada Página (so_what)

Cada página deve gerar uma frase conclusiva, sem deixar espaço para o público adivinhar.

Página	Padrão da Frase Conclusiva
Conclusão em uma página	"A receita está basicamente dentro do orçamento, o custo foi o único ponto de perda deste mês; primeiro resolver os custos, a taxa de arrecadação se recuperará naturalmente."
Receita	"A lacuna de X mil reais em operações diversas precisa ser recuperada no próximo mês; a receita de áreas comuns não pode ser incluída no lucro operacional para maquiar o resultado."
Custos	"Os dois primeiros desvios são parcialmente controláveis, são itens que devem ser corrigidos este mês; os dois últimos são fatores incontroláveis/de critério."
Taxa de Arrecadação	"A taxa de arrecadação é a consequência da qualidade do serviço: a taxa de fechamento de reclamações deste mês é de X%, a taxa de pontualidade de reparos é de Y%, estas são as causas upstream da lacuna na taxa de arrecadação."
Eficiência Per Capita	"A eficiência não piorou, mas a taxa de custo de mão de obra subiu por dois meses consecutivos, exigindo um ajuste estrutural no próximo mês no escalonamento de turnos e na liquidação de terceirizados."
Atribuição de anomalias	"O atraso na ação do mês passado (XXX) é a causa direta do estouro de energia; este mês deve ser fechado, caso contrário, se repetirá no próximo mês."
Resumo e Ações	"Meta para o próximo mês: Receita de X mil, reduzir taxa de custos para abaixo de Y%; Alerta de risco: XXX precisa ser solicitado com antecedência."

4.3 Disciplina de Expressão de Conteúdo

Estas 6 regras determinam se o relatório é profissional e devem ser seguidas na fase de geração de conteúdo:

1. O título deve conter a conclusão, não o nome da seção. ❌ "Análise de Custos" → ✅ "Custos excedem o orçamento em R$ 39.000,00, pessoal e energia juntos respondem por 92% do desvio"
2. Cada página deve ter uma frase so what. Abaixo do gráfico, deve haver uma linha de conclusão
3. Os números devem vir acompanhados de critério e período. ❌ "Taxa de arrecadação 92%" → ✅ "Taxa de arrecadação do período 92,0% (critério: recebido no mês / a receber no mês, excluindo recuperação de inadimplência antiga)"
4. Semântica de cores fixa em todo o documento: Dentro do orçamento = Verde (#2EA06A), Alerta = Amarelo (#E8A31D), Fora do orçamento = Vermelho (#D9453D)
5. Atribuição de anomalias deve formar um ciclo fechado: Item / Valor do desvio / Taxa de desvio / Causa principal / Controlabilidade / Departamento responsável / Prazo
6. Detalhes no apêndice, apenas o gráfico de conclusão no corpo principal

4.4 Gerar Script de Apresentação

Seguindo o modelo em references/03-模型deApresentação.md, gerar para cada página um script em três seções:

Seção	Conteúdo	Duração
Conclusão primeiro	Qual é a conclusão desta página	10 segundos
Suporte de dados	Números-chave + Critério + Quadro de referência	30 segundos
Causa principal e ação	Por que + Quem + Quando + Como verificar	30 segundos

Linhas vermelhas do script:

1. Primeiro a conclusão, depois o processo
2. Quantificadores devem ser executáveis: ❌ "Reduzir custos e aumentar eficiência" → ✅ "Horas extras reduzidas em 30% em relação ao mês anterior, conferência no final do mês"
3. Não fale sem números: Qualquer adjetivo deve ter um número como base
4. Verificável: Cada número deve poder responder "de onde foi consultado"
5. Assuma proativamente os problemas controláveis: Primeiro diga "É minha responsabilidade, vou corrigir até quando"
6. Se não souber responder, não invente: A resposta padrão é "Preciso verificar esse número com o financeiro, darei uma resposta por escrito até o final do expediente de hoje"

---

Estágio 5: Chamar Ferramenta PPT

5.1 Executar Script de Geração

Depende da biblioteca python-pptx, execute o script de geração desta skill:

pip install python-pptx
python <skill-dir>/scripts/build_deck.py

O script lê o dicionário DATA e gera uma apresentação editável 16:9 (33,867 × 19,05 cm).

build_pptx(data, output_path) produz 4 arquivos (mesmo nome, extensões diferentes):

Arquivo	Conteúdo
<nome>.pptx	Corpo da apresentação
<nome>.speech.json	Script de apresentação página por página (versão legível por máquina da entrega ③)
<nome>.speech.md	Script de apresentação página por página (pode ser colado diretamente no corpo do chat)
<nome>.deck.json	Metadados página ↔ seção (para verificação de alinhamento pela ferramenta de verificação)

Para adicionar uma nova página: Copie o padrão de função de página do script:

add_slide() → header(s, idx, título conclusivo, rótulo da seção) → gráfico → so_what(s, frase conclusiva)

Ao adicionar uma seção, lembre-se de registrar as palavras-chave de conteúdo da seção em SECTION_KEYWORDS; caso contrário, a ferramenta de verificação não conseguirá verificar o conteúdo de cada página.

5.2 Verificação Estrutural (Obrigatória)

Chame a ferramenta pptx_check do Centro de Capacidades para realizar a verificação estrutural, produzindo checks.json:

router.execute("pptx_check", {
    "file_path": "<saída>.pptx",
    "expected_count": <número de páginas>,
    "must_contain": "Atribuição de itens anômalos,Taxa de arrecadação do período,Per capita,Ações",
    "out": "<saída>.checks.json",
})

Ela verifica os seguintes itens e fornece um veredito pass / warn / fail:

Verificação	Descrição
package / ooxml / open	Legalidade do arquivo, estrutura do pacote OOXML, capacidade de abrir
aspect	Se é 16:9
count	Se o número de páginas está dentro do esperado
contains	Se o conteúdo-chave está presente
section_content	Verifica página por página o "conteúdo-chave que a seção deve ter"
so_what	Se cada página tem uma frase conclusiva no rodapé (exceto capa, roteiro, apêndice)
overflow	Se o texto transborda da forma (estimativa baseada em métricas de fonte)
color_semantics	Se foram usadas apenas as cores semânticas definidas
chart_data	Se o número de categorias/séries do gráfico é consistente com a fonte
no_empty_slide	Se há páginas em branco

Critério de veredito: qualquer fail → deve corrigir antes de entregar; warn → requer confirmação manual (geralmente erro de estimativa).

overflow é uma estimativa, não uma renderização real. Se houver warn e poucos itens, é normal; se houver muitos itens ou o texto estiver claramente cortado, use a verificação visual em 5.3 para confirmar.

Se o nome da ferramenta não estiver disponível, recue para chamar a função do módulo diretamente: tool.common.pptx_check_tool.check_pptx(...).

5.3 Verificação Visual (Opcional, depende do ambiente)

libreoffice --headless --convert-to png <arquivo.pptx> --outdir preview

⚠ O ambiente pode não ter o LibreOffice instalado. Se não estiver disponível, recue para:

• Usar python-pptx para ler as formas e o texto de cada página e verificar manualmente as páginas-chave; ou
• Usar PIL para desenhar miniaturas aproximadas com base no tamanho da página (apenas para ver a distribuição do layout, não equivalente à renderização real).

Verificar página por página: se o texto foi cortado, se os números nos gráficos são consistentes com a fonte de dados, se a semântica de cores é uniforme.

5.4 Entrega

Entregar três itens simultaneamente:

1. Arquivo PPTX — Apresentação editável 16:9
2. checks.json — Relatório de verificação de integridade estrutural (produzido por pptx_check, veredito deve ser pass)
3. Script de Apresentação — Escrito diretamente no corpo do chat, formato conforme references/03-模型deApresentação.md, com tabela de alocação de tempo + plano de contingência para perguntas da liderança (≥6 grupos)

---

Armadilhas e Antipadrões

• ❌ Começar falando de uma disputa de reclamação específica — sem a base operacional, o público não consegue sentir a gravidade
• ❌ Apresentar uma lista interminável de números — apenas "quanto é", sem "por que" e "e daí"
• ❌ Apenas relatar o valor do desvio, sem o responsável — não é possível gerar tarefas na reunião
• ❌ Usar "fatores objetivos" como explicação — deve-se cair em eventos específicos
• ❌ Não reportar o status das ações do mês anterior — o relatório perde o ciclo fechado
• ❌ Relatar apenas um número para a taxa de arrecadação — deve-se decompor em período / acumulado / inadimplência antiga / antiguidade

Estrutura de Diretórios

ppt_skill/
├── SKILL.md                          # Este arquivo: Instruções do pipeline de cinco estágios
├── references/
│   ├── 01-模型deRelatório.md                # Estrutura de seis seções, controle de páginas, disciplina de expressão
│   ├── 02-模型deIndicadoreseAtribuição.md          # Tabela de critérios de indicadores, atribuição em três camadas, escolha de gráficos
│   └── 03-模型deApresentação.md                # Modelo de script página por página, alocação de tempo, plano de contingência para perguntas
├── assets/
│   └── Exemplo-Análise de Desempenho Mensal de Projeto Imobiliário.pptx
├── scripts/
│   └── build_deck.py                 # Script de geração (basta alterar DATA para reutilizar)
└── checks.json                       # Exemplo de relatório de verificação histórica (regenerado pelo pptx_check em tempo de execução)

Ferramentas de Capacidade das Quais Depende

Capacidade	Localização	Uso	Obrigatória
pptx_check	tool/common/pptx_check_tool.py	Verificação estrutural do Estágio 5.2, produz checks.json	Obrigatória
LibreOffice	Programa externo	Verificação visual do Estágio 5.3 (converter para PNG)	Opcional, se não instalado, faz downgrade

pptx_check é uma ferramenta genérica independente desta skill, fornecida através do Centro de Capacidades:

from core.capability import CapabilityRouter
from tool.common.pptx_check_tool import PptxCheckTool

router = CapabilityRouter()
router.add_tool(PptxCheckTool())  # A skill e a ferramenta são registradas no mesmo nível

A skill não é uma Tool, portanto o registro usa add_skill (build_capability_router lida automaticamente), enquanto pptx_check é uma ferramenta, usa add_tool.