O skill do agente está instalado, o servidor MCP conectado e o agente acessa os dados da operação em tempo real. As respostas chegam rápido. Mesmo assim, há uma distância entre o que o agente responde e o que o coordenador de turno precisa: quando você pergunta pela cobertura da zona norte, o agente devolve o número, mas não diz se esse número é problemático para aquela cidade numa terça-feira às 18h. Quando você pergunta como lidar com motoristas fora da área principal durante um pico, ele dá opções razoáveis, mas não a resolução que você encontrou há dois meses e que funcionou naquele contexto específico. Essa distância entre "responder" e "diagnosticar" tem uma única causa: o arquivo de contexto do operador não contém a informação que transformaria os dados da API em diagnósticos específicos para aquela operação.

Este artigo não é sobre o skill base nem sobre como separar as camadas de configuração para manter as atualizações sem conflitos — isso está coberto no artigo sobre o fork do skill público. É sobre o conteúdo do arquivo de contexto do operador: quais seções o tornam útil, quais dados concretos entram em cada uma, quanto detalhe é suficiente para uma primeira versão funcional, e quais erros transformam o arquivo em algo que existe mas não produz diagnósticos diferentes dos que o agente daria sem ele. O artigo é dirigido ao operador que já tem o agente ativo e percebe que as respostas dele são corretas, mas genéricas demais para serem diretamente acionáveis.

Por que o arquivo determina o teto do que o agente pode diagnosticar

O agente opera sobre dois tipos de dados: os que obtém em tempo real da API da plataforma — motoristas ativos, cobertura atual, corridas em andamento, cancelamentos da última hora — e os que estão no seu contexto de sistema: as convenções da operação que definem o que cada número significa. A plataforma fornece o primeiro conjunto; o operador fornece o segundo. Quando esse segundo conjunto está vazio ou é genérico demais, o agente tem acesso aos dados corretos, mas não tem o ponto de referência para interpretá-los: sabe que há doze motoristas ativos na zona norte, mas não sabe se isso é suficiente, baixo ou crítico para aquela zona naquele horário.

A diferença prática entre um agente com um arquivo de contexto bem construído e um sem ele não é de velocidade nem de acesso a dados — é de especificidade. Com o arquivo, o agente pode responder: "a zona norte está com doze motoristas ativos, 30% abaixo do limite mínimo para as tardes de terça-feira na alta temporada; da última vez que caiu para esse nível em condições semelhantes, o padrão que funcionou foi realocar dois motoristas da zona centro antes das 18h30". Sem o arquivo, o agente dá a mesma resposta para qualquer operação com doze motoristas em uma zona: descreve o número e deixa a interpretação para o coordenador. Essa é a diferença entre uma ferramenta que amplifica o critério do coordenador e uma que devolve dados sem referência.

As cinco seções que distinguem um arquivo útil de um de enchimento

Um arquivo de contexto que produz diagnósticos específicos tem cinco seções. Não é a única estrutura válida, mas é a que fecha as lacunas de informação mais comuns em operações que já têm o agente ativo há mais de trinta dias:

Zonas e limites: o vocabulário compartilhado e os números que o tornam específico

As definições geográficas resolvem o problema mais frequente em operações onde a equipe usa nomes internos que não coincidem com os identificadores do sistema. O agente que recebe uma pergunta sobre "a zona industrial" precisa saber se esse nome corresponde à zona norte do painel, se inclui ou exclui o acesso pela rodovia federal, e se, nesse contexto, "zona industrial" no turno noturno se refere aos três polígonos do sistema ou só ao principal. Sem essa correspondência, o agente trabalha com ambiguidade — cada resposta pode se referir a uma geografia diferente dependendo de como o coordenador formulou a pergunta — e esse custo se acumula em diagnósticos inconsistentes.

Os limites operacionais são a seção mais diretamente conectada à qualidade do diagnóstico, porque são eles que permitem ao agente interpretar um número em vez de simplesmente devolvê-lo sem referência. Um limite bem documentado não diz "disponibilidade baixa na zona norte" — diz "menos de 14 motoristas ativos na zona norte entre 17h e 20h de segunda a sexta é nível de alerta; menos de 8 motoristas nesse mesmo período é nível crítico, que justifica ativar incentivos de realocação". Essa especificidade permite ao agente comparar o estado atual com a referência daquela operação e gerar um diagnóstico acionável em vez de um dado neutro que o coordenador precisa interpretar sem contexto.

Incidentes e resoluções: a memória que elimina o diagnóstico do zero

A seção de incidentes e resoluções é onde mais varia a qualidade entre arquivos que produzem diagnósticos úteis e arquivos que existem sem fazer diferença. A distinção entre um registro útil e um de enchimento é concreta: um registro útil descreve a situação com seus parâmetros específicos, a decisão que o coordenador tomou, o resultado observável nos trinta minutos seguintes e o contexto que explica por que aquela decisão funcionou. Um registro de enchimento diz "zona norte sem cobertura, incentivo ativado, resolvido" — isso não tem nada que o agente não pudesse inferir sozinho. O que transforma o registro em algo útil é o detalhe que não está nos dados: que, naquele caso específico, a zona sul também estava baixa e mover motoristas de lá não era viável, que a resolução correta foi o incentivo de ponto fixo em vez do de zona geral.

O formato concreto para um registro de incidente bem documentado tem quatro campos. Situação: o que estava acontecendo no momento do incidente, com os números específicos de cobertura, cancelamentos pendentes e solicitações sem atribuição. Contexto: o que era incomum ou explicativo — um evento próximo, fim do turno escolar, chuva, dia de pagamento. Ação: a decisão tomada com seus parâmetros exatos — quantos motoristas, para qual zona, que tipo de incentivo, em qual janela de tempo. Resultado: o que mudou nos quinze ou trinta minutos seguintes. Quando o agente tem vinte ou trinta registros nesse formato, o tempo de diagnóstico em incidentes recorrentes cai de dez ou quinze minutos para dois ou três, porque o agente consegue identificar o padrão e recuperar a resolução em vez de construir um diagnóstico do zero.

A primeira versão em duas horas: o que incluir e o que deixar para depois

O erro mais comum ao construir o arquivo de contexto pela primeira vez é tentar documentar tudo antes de começar a usá-lo. Um arquivo que tenta cobrir todos os cenários possíveis na primeira sessão leva dias de trabalho e acaba cheio de hipóteses sobre situações que ainda não aconteceram — que o agente consegue inferir dos dados com quase a mesma precisão. O que ele não consegue inferir, por exigir conhecimento local, são três coisas: os nomes internos das zonas e a correspondência deles com os identificadores do sistema, os limites das três ou quatro zonas principais nas faixas horárias de maior demanda, e os dois ou três incidentes recorrentes mais custosos com suas resoluções documentadas.

Uma primeira versão funcional pode ser construída em duas horas usando o próprio agente como parceiro de trabalho. O processo concreto: exportar a lista de zonas do painel, pedir ao agente que use essa lista como base e formule as perguntas de limite que precisa que o operador responda (isso leva entre vinte e trinta minutos), depois documentar os dois ou três incidentes mais recorrentes com o formato de quatro campos (quarenta a sessenta minutos). O que fica fora dessa primeira sessão — padrões sazonais, motoristas individuais, eventos locais — é adicionado em sessões curtas depois de turnos em que ocorreram incidentes relevantes. O arquivo cresce com o uso, não em uma sessão de design inicial, e cada incidente documentado em tempo real produz um registro mais preciso do que os reconstruídos de memória semanas depois.

Os três padrões que tornam um arquivo tecnicamente presente, mas operacionalmente vazio

O primeiro padrão que elimina a utilidade do arquivo é a ausência de números específicos. Descrever que "a zona norte tem disponibilidade baixa nos horários de pico" não acrescenta nada que o agente não consiga inferir dos dados em tempo real. O que agrega valor é o limite: quantos motoristas exatamente é "baixo" naquela zona, naquele horário, para aquele operador naquela cidade. Sem esse número, o agente não consegue comparar o estado atual com a referência específica da operação e produz a mesma resposta que daria sem o arquivo: correta, mas genérica, útil para confirmar o estado, mas não para diagnosticar se esse estado exige ação.

O segundo padrão é documentar apenas o estado da operação sem as resoluções de incidentes passados. Um arquivo cheio de descrições de zonas e padrões é útil para responder perguntas de estado — como está a cobertura, quantos motoristas estão ativos, quais zonas têm mais cancelamentos — mas não para reduzir o tempo de diagnóstico nos momentos críticos do turno, que é exatamente onde o agente produz mais valor com o contexto correto. O terceiro padrão é usar no arquivo nomes que não coincidem com os identificadores do sistema: se o arquivo diz "zona industrial" e a plataforma registra a zona como "Zona_Norte_03", o agente gasta parte do seu contexto resolvendo a ambiguidade antes de chegar à resposta — esse custo de desambiguação se repete a cada consulta e degrada a especificidade de cada diagnóstico.

O arquivo de contexto do operador não é um documento de integração construído uma única vez na instalação do skill — é um registro operacional que cresce a cada turno em que acontece algo que vale a pena documentar. Cada incidente registrado com sua resolução, cada limite ajustado à temporada atual, cada padrão sazonal documentado antes de chegar, é contexto que o agente pode usar na próxima consulta para produzir um diagnóstico mais específico do que o anterior. Esse crescimento por acumulação não pode ser replicado sem o tempo de operação: é o único insumo que nenhuma configuração genérica da plataforma consegue fornecer no momento da instalação do skill.

Os operadores que chegam aos seis meses com um arquivo bem mantido têm algo que nenhuma configuração da plataforma consegue entregar diretamente: a inteligência específica da sua cidade, das suas zonas e da sua operação, acumulada turno a turno em um formato que o agente pode usar para responder perguntas que não têm resposta genérica. Essa especificidade é o que faz a mesma pergunta sobre cobertura na zona norte produzir diagnósticos diferentes para operadores que usam a mesma plataforma com os mesmos dados em tempo real. A diferença não está no skill — está no contexto que cada operador construiu.