jcosxgb/graphe

Graphe — Uma Pergunta, Executada como um Grafo

Transforme uma pergunta ou fluxo de trabalho consequente em um grafo de evidências em estágios:

PLANEJAR → PISTAS PARALELAS → CÉTICO → MESCLAR → PORTÃO HUMANO

Esta habilidade é invocada explicitamente com:

/graphe <pergunta ou fluxo de trabalho>

Quando Usar

Use /graphe quando o usuário explicitamente quiser que uma pergunta, decisão, investigação ou fluxo de trabalho proposto consequente seja decomposto em pistas de evidências independentes, desafiado por um cético separado e retornado a um portão de decisão humano. É especialmente útil para validação de mercado, escolhas técnicas, design operacional e decisões onde evidências fracas poderiam causar trabalho desperdiçado. Não o ative implicitamente para perguntas comuns; o comando de barra é o opt-in.

Uma invocação é um opt-in deliberado para trabalho multiagente. Não a rebaixe a uma resposta comum de agente único meramente porque a pergunta parece simples.

Princípios de Design

• Defina o resultado final antes de desenhar os trabalhos.
• Trate o grafo como trabalhos conectados por setas; as setas codificam dependências reais, e as notas/resultados compartilhados são o estado.
• Construa o menor grafo que melhore materialmente a qualidade. Mais agentes podem criar ruído duplicado.
• Remova espera falsa: trabalhos independentes executam em paralelo; trabalhos dependentes esperam.
• Separe trabalhadores de revisores. Os pesquisadores não avaliam seu próprio trabalho.
• Pare quando a resposta for suficientemente boa para o critério de decisão indicado.
• Preserve estado útil—plano, evidências, fontes, vereditos do cético e decisão—quando o usuário solicitar uma trilha de papel reutilizável ou o espaço de trabalho já tiver uma convenção de artefato de pesquisa.
• A ferramenta de orquestração é secundária ao fluxo de trabalho. Para um novo grafo recorrente, prove a forma manualmente antes de adicionar uma estrutura mais pesada ou automação externa.

Regras Inegociáveis

1. A sequência é rigorosa. Não mescle antes que o cético termine. Não execute a recomendação antes do portão humano.
2. As pistas de pesquisa são somente leitura. Elas podem inspecionar fontes, arquivos, sistemas e informações públicas, mas não devem publicar, enviar, comprar, deletar, implantar, modificar produção ou contatar pessoas.
3. Evidência é em nível de alegação. Toda alegação factual material precisa de uma URL/caminho de fonte, tipo de fonte e confiança. “O subagente disse” não é evidência.
4. Fontes primárias vencem. Prefira documentos oficiais, dados de primeira parte, código-fonte, contratos, evidência direta de clientes ou registros originais. Rotule evidência secundária e inferência.
5. O cético é um trabalho separado. Ele ataca independentemente as alegações, verifica fontes originais, encontra contradições e marca cada alegação como manter, qualificar ou rejeitar.
6. Apenas sobreviventes mesclam. Alegações rejeitadas não podem aparecer como fatos na recomendação final.
7. O humano escolhe o próximo passo. Use a ferramenta clarify para o portão. Nunca escolha silenciosamente ou comece uma opção.
8. Sem paralelismo falso. Use uma única chamada delegate_task(tasks=[...]) em lote para pistas independentes. Não faça chamadas filhas sequenciais para pistas paralelas.
9. Respeite a delegação assíncrona do Hermes. Após um lote ser despachado, não faça polling ou reivindique conclusão. Os resultados da pesquisa reentram na conversa quando todas as pistas terminam; então lance o cético.
10. Mantenha a saída no tamanho de uma decisão. A mescla é uma recomendação de uma página, não um despejo de cada relatório de pista.

Estágio 0 — Analisar a Invocação

Trate o texto após /graphe como a pergunta. Palavras de modo opcionais podem ser fornecidas:

• fast: 2 pistas, passagem estreita de evidências.
• standard: 3 pistas; padrão.
• deep: 3 pistas com cobertura de fonte mais ampla e lacunas explícitas de acompanhamento.

Se nenhuma pergunta for fornecida, faça um esclarecimento aberto: “Qual pergunta ou fluxo de trabalho devo executar como um grafo?” Não comece a pesquisa sem um alvo.

Estágio 1 — PLANEJAR

O agente pai é dono do planejamento. Antes de delegar, produza um plano de grafo compacto com:

• Decisão/pergunta — uma frase.
• Critério de saída — o que uma resposta útil deve decidir ou habilitar.
• Restrições — tempo, mercado, jurisdição, orçamento, limites de repositório/sistema e efeitos colaterais proibidos.
• Pistas — 2 ou 3 trabalhos de pesquisa ortogonais, cada um com uma pergunta clara e critério de parada.
• Portão — estado que a execução aguarda a escolha humana.

Escolha pistas para o domínio em vez de reutilizar rótulos cegamente.

Padrões de pista padrão

Para perguntas de mercado/produto/negócios, prefira:

1. Dor do cliente / comportamento atual — como o usuário-alvo lida com o problema hoje; evidência direta, soluções alternativas, urgência e disposição para mudar.
2. Concorrentes / alternativas / economia — quem já resolve, substitutos, posicionamento, preços, custos de mudança e modos de falha.
3. Distribuição / execução / restrições — como o público é realmente alcançado, viabilidade operacional, restrições legais/de segurança e custo para testar.

Para pesquisa geral ou decisões técnicas, prefira:

1. Verdade fundamental / estado atual — fatos primários, requisitos e comportamento do sistema.
2. Alternativas / contraevidências — abordagens concorrentes, evidências desconfirmadoras e trade-offs.
3. Execução / risco / verificação — caminho de implementação, dependências, modos de falha e como testar com segurança.

Para fluxos de trabalho de implementação, mantenha todas as pistas somente leitura até o portão. Agentes paralelos podem inspecionar áreas diferentes, mas não devem editar o mesmo checkout ou criar efeitos colaterais externos.

Evite pistas redundantes. Se duas pistas buscassem as mesmas fontes para as mesmas alegações, redesenhe-as.

Estágio 2 — PESQUISAR EM PARALELO

Chame delegate_task uma vez com um lote de 2–3 tarefas folha. Dê a cada filho a pergunta completa, restrições compartilhadas, sua missão de pista, o contrato de evidências abaixo e o idioma de saída exigido.

Use um output_schema tolerante por tarefa exigindo apenas campos que o pai lerá:

{
  "type": "object",
  "required": ["pista", "resumo", "alegacoes", "lacunas"],
  "properties": {
    "pista": {"type": "string"},
    "resumo": {"type": "string"},
    "alegacoes": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["id", "alegacao", "evidencia", "fonte", "localizador", "tipo_fonte", "confianca"],
        "properties": {
          "id": {"type": "string"},
          "alegacao": {"type": "string"},
          "evidencia": {"type": "string"},
          "fonte": {"type": "string"},
          "localizador": {"type": "string"},
          "observado_ou_publicado_em": {"type": "string"},
          "tipo_fonte": {"type": "string"},
          "confianca": {"type": "string"},
          "premissas": {"type": "array"},
          "ressalva": {"type": "string"}
        }
      }
    },
    "contradicoes": {"type": "array"},
    "lacunas": {"type": "array"},
    "proximos_passos_candidatos": {"type": "array"}
  }
}

Contrato de evidências da pista

Cada pista deve:

• Investigar independentemente; não coordenar com pistas irmãs.
• Usar fontes atuais e originais quando acessíveis.
• Citar uma URL, caminho de arquivo com referência de linha/página ou identificador de registro direto para cada alegação material.
• Atribuir IDs de alegação estáveis e incluir uma citação, página, linha, seção, timestamp ou outro localizador quando disponível.
• Separar fato observado, alegação relatada, cálculo e inferência.
• Incluir datas para evidências sensíveis ao tempo.
• Relatar evidências contraditórias e desconhecidos, não ocultá-los.
• Se faltar contexto, relatar o bloqueador ou rotular claramente uma suposição; filhos não podem pedir esclarecimento e não devem adivinhar.
• Parar quando seu critério de parada declarado for atingido ou quando pesquisa adicional tiver retornos acentuadamente decrescentes.
• Não fazer alterações externas.

Após a ferramenta de despacho confirmar que o lote está em execução, indique brevemente quais pistas estão ativas. Não invente seus resultados e não faça polling.

Estágio 3 — CÉTICO

Quando os resultados consolidados das pistas reentrarem na conversa, normalize-os em uma matriz de alegação/evidência indexada pelo ID de alegação estável, então lance uma nova tarefa folha delegate_task como o cético. Forneça a pergunta original, restrições, matriz normalizada e todas as saídas das pistas.

O cético deve:

1. Atacar primeiro as alegações de maior impacto para a decisão.
2. Abrir/verificar a fonte original citada quando acessível; uma string de citação sozinha é insuficiente.
3. Testar qualidade da fonte, atualidade, relevância, viés de amostra, saltos causais, suposições ocultas, aritmética, dependência de fonte e corroboração circular.
4. Pesquisar especificamente por evidências desconfirmadoras e contradições entre pistas.
5. Marcar cada alegação como manter, qualificar ou rejeitar, dar um motivo e rotular o defeito como fatal, material ou menor quando aplicável.
6. Distinguir erros factuais de discordâncias de preferência.
7. Identificar qual evidência mudaria a decisão e a menor verificação adicional que poderia resolver cada objeção material.
8. Recomendar no máximo três próximos passos de baixo custo que resolvam as maiores incertezas.
9. Não realizar efeitos colaterais.

Use um esquema de saída exigindo:

{
  "type": "object",
  "required": ["vereditos_alegacoes", "contradicoes", "riscos_decisao", "melhores_testes_seguintes"],
  "properties": {
    "vereditos_alegacoes": {"type": "array"},
    "contradicoes": {"type": "array"},
    "riscos_decisao": {"type": "array"},
    "melhores_testes_seguintes": {"type": "array"}
  }
}

Após despachar o cético, indique que o ataque de evidências está em execução. Não mescle cedo e não faça polling.

Estágio 4 — MESCLAR

Quando o resultado do cético retornar, o agente pai cria uma recomendação de uma página usando apenas alegações manter e qualificar claramente qualificadas. Reabra qualquer fonte necessária para resolver uma ambiguidade material; resumos de subagentes não são prova de efeitos colaterais externos ou estado do sistema ao vivo.

Use esta estrutura exata:

# Recomendação

**Decisão:** <uma frase>
**Confiança:** <baixa / média / alta, com motivo em uma linha>

## Porquê
- <alegação sobrevivente + citação>
- <alegação sobrevivente + citação>
- <alegação sobrevivente + citação>

## O que não sobreviveu
- <alegação rejeitada ou materialmente enfraquecida + motivo>

## Principais riscos e desconhecidos
- <risco/desconhecido>

## Melhores próximos passos
1. <menor teste que reduz a maior incerteza>
2. <segunda opção>
3. <terceira opção, apenas se útil>
4. Passar — não tomar nenhuma ação agora

Mantenha aproximadamente uma página renderizada. Vincule ou cite fontes inline. Coloque material detalhado das pistas em um apêndice apenas se o usuário pedir.

Estágio 5 — PORTÃO HUMANO

Imediatamente após a mescla de uma página, chame clarify no modo de seleção única com não mais que quatro escolhas:

• Até três próximos passos concretos derivados das evidências.
• Sempre incluir Passar — não tomar nenhuma ação agora.

Coloque cada opção apenas no array choices; não duplique as escolhas no texto da pergunta. Pergunte: “Qual próximo passo você deseja autorizar?”

Não execute nenhuma opção até que a seleção do usuário chegue. A invocação /graphe em si nunca é aprovação para um efeito colateral. Após a seleção:

• Reafirme o próximo passo selecionado e o escopo analítico autorizado em uma frase.
• Se o passo for enviar uma mensagem, publicar, comprar, alterar uma conta, implantar, deletar um arquivo, modificar uma API ou causar outro efeito colateral externo, apresente o alvo/conta/espaço de trabalho exato, payload/comando/alteração proposto, custo e público esperados, reversibilidade/plano de reversão, estratégia de prevenção de duplicatas, método de verificação e riscos não resolvidos antes da execução; obtenha qualquer aprovação adicional que as regras de segurança comuns exigirem.
• Execute apenas o passo autorizado.
• Aplique regras comuns de segurança/aprovação para envios, compras, implantações, ações destrutivas, segredos ou alterações em produção.
• Leia de volta ou busque o objeto resultante e relate apenas efeitos verificados independentemente.

Comportamento de falha e fallback

• Uma pista falha: Tente novamente uma vez apenas se a falha for transitória. Caso contrário, continue com as pistas restantes e reduza proeminentemente a confiança.
• Fontes inacessíveis: Relate a falha de acesso; nunca substitua evidência faltante por prosa plausível.
• Pistas conflitantes: Preserve o conflito através do estágio do cético. Não faça média de alegações incompatíveis.
• Delegação indisponível: Diga que o grafo multiagente solicitado não pode ser executado como projetado. Ofereça um fallback de agente único claramente rotulado; não o substitua silenciosamente.
• Pergunta muda durante a execução: Pare o grafo antigo, reafirme a decisão revisada e replaneje. Não mescle resultados de pistas não relacionadas na nova pergunta.
• Solicitação insegura ou não permitida: Regras de segurança normais sobrepõem o grafo. Recuse ou restrinja a parte insegura enquanto preserva a análise segura.

Lista de verificação de qualidade

Antes de abrir o portão humano, confirme:

• O pai produziu um plano explícito.
• 2–3 pistas independentes executaram em um lote paralelo.
• Toda alegação material tem evidência rastreável.
• Um cético separado atacou as evidências.
• Alegações rejeitadas foram excluídas da recomendação.
• A mescla é concisa e orientada à decisão.
• Nenhum efeito colateral externo ocorreu antes do portão.
• O humano recebe escolhas concretas incluindo Passar.