danepps/pesquisa-jurídica

Pesquisa Jurídica

Aproxima uma execução de pesquisa aprofundada, especializada para direito e ajustada para ser eficiente por padrão. Ela executa um pipeline de recuperação sobre fontes jurídicas gratuitas / da web aberta apenas (sem Westlaw/Lexis); a forma, os limites e o mapa de modelos de cada etapa residem no passo 4, junto com a invocação. O design mantém o uso de tokens baixo — o custo dominante em uma distribuição ingênua é um modelo de fronteira lendo cada página buscada — enquanto ainda previne citações alucinadas. Adicione deep (ex.: "faça uma passagem aprofundada") para trabalhos de alto risco onde a minúcia supera a velocidade.

Fontes (web aberta)

Jurisprudência: CourtListener, Justia, Google Acadêmico (jurisprudência), Cornell LII, Caselaw Access Project, sites oficiais de tribunais. Acadêmico: SSRN, Google Acadêmico, repositórios digitais de faculdades de direito, conteúdo aberto da HeinOnline, sites de periódicos, páginas de professores. Os modos acadêmicos também pesquisam a própria biblioteca Zotero do usuário através do servidor MCP do Zotero (ignorado graciosamente se indisponível).

Como executar

1. Analisar a solicitação

Extraia do prompt do usuário:

• pergunta — a questão jurídica (obrigatório).
• modo — jurisprudencia, academico ou ambos. Padrão ambos. Infira pela redação ("o que os tribunais decidem" → jurisprudência; "estado da literatura / debate acadêmico" → acadêmico).
• estiloSaida — praticante (Questão Apresentada / Resposta Breve / IRAC) ou academico (introdução / panorama / análise / notas de rodapé). Padrão: praticante para jurisprudência, acadêmico para acadêmico e para ambos. Respeite uma substituição explícita.
• jurisdicao, dataBase (padrão hoje) e quaisquer observacoes (fatos, postura, escopo).

2. Esclarecer apenas se realmente impeditivo

Se a pergunta for muito vaga para ser pesquisada bem, faça 2–3 perguntas direcionadas antes de lançar. Para jurisprudência, jurisdição e postura processual são mais importantes; para acadêmico, a tese específica ou subquestão e qualquer janela temporal. Não pergunte demais — escolha padrões sensatos e anote-os.

3. Pré-voo: garantir que ferramentas web estejam permitidas (faça isso ANTES de lançar)

Os subagentes de pesquisa chamam bastante WebSearch e WebFetch. Se essas ferramentas não estiverem pré-autorizadas, cada chamada gera um prompt de permissão interativo — e um prompt interrompido pode matar um agente de pesquisa no meio da execução (um modo de falha real: uma execução anterior perdeu 2 de 4 vetores assim).

Antes de chamar o Workflow, torne a execução autocontida:

1. Leia ~/.claude/settings.json e verifique permissions.allow por "WebFetch" e "WebSearch".
2. Se algum estiver faltando, adicione-o (mescle no array allow existente — nunca o substitua; crie o caminho permissions.allow se ausente). Se ambos já estiverem presentes, não faça nada.
3. Não pergunte ao usuário sobre isso — é configuração de rotina para a skill. (Se o arquivo for gerenciado/ somente leitura e você não puder editá-lo, informe ao usuário que verá prompts por busca e deve aceitá-los, ou adicione a regra via /permissions.)
4. Opcional, mas vale a pena dar uma olhada: a verificação determinística de citações de casos precisa de um token da API do CourtListener. Teste-o, não saia procurando um arquivo — execute python3 ${CLAUDE_PLUGIN_ROOT}/skills/legal-research/check_cite.py "347 U.S. 483"; saída 0 com "found": true significa que o token está funcionando e não há nada a relatar. check_cite.py resolve o token de COURTLISTENER_API_TOKEN, depois COURTLISTENER_TOKEN, depois do arquivo ~/.config/courtlistener/token — nessa ordem, e a rota de variável de ambiente (comumente definida no bloco env de ~/.claude/settings.json) é a instalação normal, então a ausência do arquivo não prova nada. Se a verificação realmente falhar, não bloqueie a execução — os agentes de verificação recorrem à checagem web — mas mencione isso uma vez no passo de entrega (página do token: https://www.courtlistener.com/profile/api-token/).

4. Lançar o workflow

Chame a ferramenta Workflow com o script incluído e os argumentos analisados:

Workflow({
  scriptPath: "${CLAUDE_PLUGIN_ROOT}/skills/legal-research/legal-research.workflow.js",
  args: {
    skillsDir: "${CLAUDE_PLUGIN_ROOT}/skills",      // onde os scripts auxiliares incluídos residem
    question: "<a questão jurídica>",
    mode: "jurisprudencia" | "academico" | "ambos",
    estiloSaida: "praticante" | "academico",
    jurisdicao: "<ex.: federal / 9º Circ. / Missouri / Supremo Tribunal dos EUA>",
    dataBase: "<AAAA-MM-DD ou 'hoje'>",
    observacoes: "<fatos, postura, escopo, qualquer coisa que o usuário enfatizou>",
    deep: false,  // true apenas quando o usuário pede uma passagem aprofundada/completa/de alto risco
    projectDir: "<o diretório de trabalho atual — permite o vetor de levantamento do corpus local;
                  omita apenas se o diretório atual claramente não estiver relacionado à pergunta>"
  }
})

Eficiente por padrão: ~4 vetores de levantamento apenas de busca (mais uma varredura da biblioteca Zotero em modos acadêmicos e uma varredura do corpus local de projectDir — memorandos anteriores e fontes baixadas são mapas e pistas, nunca autoridade citável). O Escopo também classifica a pergunta (doutrinária vs. acadêmica; histórica ou não) — isso seleciona um resumo de método analítico injetado no Rascunho (disciplina de síntese, higiene de holding/obiter dictum, taxonomia que abrange eras para questões de história doutrinária) e, para perguntas históricas, espalha os vetores de busca em camadas temporais para que a cobertura não se concentre no cânone moderno. Célula de cobertura de resposta direta (acadêmico/ambos, adicionado em 2026-07-16 após uma execução de comparação Codex vencer uma execução Claude de 64 agentes na pergunta real): O Escopo deve dedicar pelo menos um vetor a trabalhos acadêmicos que tratam do FENÔMENO NOMEADO da pergunta como seu próprio objeto — construído a partir dos termos especializados de título que um especialista espera e incluindo uma perseguição de citações da peça mais pertinente — mantido distinto das literaturas adjacentes às quais o fenômeno meramente pertence. O Levantamento sinaliza tais candidatos centrais; a Triagem os promove para leituras completas antes de levantamentos adjacentes amplos. A falha que isso corrige: mapear cinco literaturas adjacentes (discurso extrajudicial, recusa, celebridade) enquanto perde o punhado de trabalhos diretamente sobre o fenômeno (ex.: estudos de autobiografia judicial, seções de ética sobre "acordos de livros de juízes"), e então confundir essa lacuna de corpus com uma conclusão de que "nenhuma pesquisa direta existe." Alegações de ausência/lacuna agora são bloqueadas por uma auditoria de omissão de fonte central (no resumo do método acadêmico): nenhum "nenhuma pesquisa aborda diretamente X" a menos que uma busca direcionada ao fenômeno E uma perseguição de citações em ambas as direções realmente tenham ocorrido — caso contrário, a alegação é limitada a "nas fontes revisadas" e a busca não executada é sinalizada. A distribuição é organizada em células de cobertura, e o limite de agentes é um teto, não uma cota — faixas não sobrepostas vencem muitas buscas generalistas sobrepostas. Pipeline: vetores de levantamento → deduplicação → ≤8 leituras completas únicas no total (não por vetor; os leitores recorrem a espelhos de acesso aberto — repositórios digitais, páginas de autores, CourtListener/LII — antes de desistir, roteiam PDFs através de um buscador com limite de tamanho rígido, fetch_page.py, e extraem postura/limitação/opiniões divergentes/significância juntamente com a proposição e citação) → um rascunho de sessão única (guiado pelo resumo do método) → um preenchimento de lacunas limitado (≤3 recuperações direcionadas mais uma onda de repetição, apenas se o rascunho sinalizar autoridades ausentes) → checagens de citações em partes das autoridades citadas apenas (8 por agente; citações de casos confirmadas deterministicamente via API de busca de citações do CourtListener, check_cite.py, mais uma varredura sistemática de tratamento de opiniões citantes via cl_case_tools.py citing — uma sonda de linguagem de tratamento com relevância ranqueada sobre as opiniões citantes reais do caso, com uma data de atualidade, substituindo a antiga busca única; fontes que um leitor já abriu nesta execução pulam verificações de existência) → finalização leve. Candidatos não selecionados E as autoridades em que cada fonte lida se baseia são carregados no rascunho como pistas não lidas com ressalvas, para que a amplitude permaneça ampla enquanto as buscas permaneçam poucas. Cada execução é protegida por gastos: um teto flexível embutido (~250k tokens de saída no modo leve, ~1M no aprofundado — elevado de 600k em 2026-07-15 após uma execução histórica aprofundada travar no meio da escada e deixar 35 de 43 citações não verificadas) aciona a mesma escada de degradação graciosa que um orçamento explícito +500k — reduzir leituras → pular preenchimento de lacunas → verificar apenas citações essenciais — para que uma execução descontrolada degrade em vez de espiralar. Agentes de leitura, preenchimento de lacunas e verificação carregam um bloco de disciplina de acesso (adicionado na mesma data): limites máximos de tentativas, apenas WebSearch/WebFetch, e uma proibição explícita de automação de navegador, proxies de biblioteca e fluxos SSO/login — uma fonte atrás de paywall é um honesto opened=false, não uma razão para insistir. Modelos: Haiku apenas para o levantamento de trechos de busca; Sonnet para triagem, leituras completas e verificação; Escopo, Rascunho e Finalização herdam o modelo da sessão (Fable quando Fable está ativo). deep:true (ou um orçamento de tokens estilo +800k) expande para até 7 vetores, eleva o limite de leitura para 16 e dá a cada citação essencial (limitada a 8) uma passagem de refutação adversarial de 3 votos (reabre fontes para confirmar citações verbatim). O workflow é executado em segundo plano e notifica você na conclusão.

5. Entregar

O workflow retorna { memo, exitState, degradation, counts, ... }.

• Verifique exitState ANTES de apresentar. complete → entregue. complete_with_limits → entregue, destacando as lacunas documentadas (listadas em degradation e na seção de Limites do memorando). budget_exhausted → o guarda de orçamento cortou a cobertura real (leituras reduzidas, preenchimento de lacunas pulado, citações não verificadas — veja degradation para detalhes); o memorando ainda não é o produto final. O padrão de resgate comprovado (execução pré-1960 de julho de 2026): lance passagens de Agente de leitura e verificação direcionadas — uma por área descoberta, cada uma com os casos/citações específicos a buscar e confirmar contra o texto oficial do relator (CAP static.case.law / varreduras LOC usrep) — depois escreva o memorando final você mesmo a partir do núcleo verificado do workflow mais as passagens de preenchimento. Não entregue ao usuário um memorando que diz "Confiança: insuficiente" para metade de seu escopo sem preencher as lacunas ou perguntar. Agentes de resgate precisam da mesma disciplina de acesso que os agentes do workflow (lição de uma execução acadêmica de julho de 2026, onde um agente de resgate sem limites queimou 30+ minutos e ~245k tokens escalando para automação de navegador contra um artigo de 1962 atrás de paywall): escreva em cada prompt de resgate um limite máximo de tentativas (~3 por fonte), apenas WebSearch/WebFetch, uma proibição explícita de automação de navegador / proxies de biblioteca / fluxos SSO, e a instrução de que "atrás de paywall — aqui está a base mais forte que alcancei" é uma resposta totalmente aceitável. Se um agente de resgate continuar insistindo, use SendMessage para fazê-lo encerrar e relatar, em vez de esperar.
• Apresente o memorando ao usuário como produto principal.
• Hiperlinks (obrigatório, por autor, 2026-08-29): toda notícia, postagem de blog ou outra fonte web no memorando deve carregar sua URL funcional como um link clicável — nunca uma atribuição apenas por nome do veículo como "(Politico)" ou "(Roll Call, 14 de julho de 2026)". O bloco de citações do workflow impõe isso nos prompts dos agentes; mantenha edições manuais, passagens de resgate e quaisquer memorandos de pesquisa ad-hoc (não workflow) sob a mesma regra, e instrua quaisquer agentes de resgate/preenchimento a retornar a URL para cada fonte que citarem (uma reivindicação sem URL é não verificada).
• Cabeçalho do memorando de pesquisa e rodapé de produção (obrigatório, por autor — regra global em ~/.claude/CLAUDE.md): o memorando abre diretamente abaixo do título com o bloco de cabeçalho estruturado (Tópico: / Data: / Por:); o bloco Detalhes de produção: vai no final do arquivo (após todos os apêndices, incl. "Limites desta pesquisa", separado por uma linha ---) — nunca no início. Data é a data/hora local em que o memorando foi entregue/escrito; Por é Claude-<modelo da sessão orquestradora> (id exato); Detalhes de produção nomeia a skill, o(s) modelo(s) de agente workflow realmente usado(s) (lido das entradas de progresso por agente da execução — não suponha), a duração em tempo real e a contagem de tokens do bloco <usage> da notificação de conclusão (rotulado como tokens de saída do subagente; overhead do orquestrador não incluído). Se passagens de resgate/preenchimento ocorreram após o workflow, adicione suas contagens de agente e observe que a duração cobre apenas a execução do workflow.
• Exiba as contagens de verificação ("N autoridades verificadas, M não verificadas") para que saibam o quanto confiar, e aponte para o apêndice "Limites desta pesquisa" do memorando (que agora divulga a base de verificação de cada autoridade: texto completo direto / reprodução autoritativa / corroboração secundária / apenas citação).
• O resultado também carrega skeleton — o esboço analítico com tags de citação a partir do qual o rascunho foi escrito (cada reivindicação fundamental vinculada à sua descoberta, buracos marcados como GAP). Não o apresente por padrão; ofereça-o se o usuário quiser auditar o raciocínio, e use-o você mesmo ao editar o memorando manualmente (uma reivindicação sem linha no esqueleto precisa de uma autoridade ou uma ressalva antes de crescer).
• Ofereça-se para salvá-lo: Markdown no diretório de trabalho; Word via o conversor incluso — python3 ${CLAUDE_PLUGIN_ROOT}/skills/legal-research/md2docx.py memo.md memo.docx "<Título>"; ou Google Drive via o conector. Se o usuário pediu .docx antecipadamente, apenas produza-o.
• Ofereça uma passagem de acompanhamento em qualquer ponto fraco/não verificado, ou uma troca de estilo de saída.

Calibração de reivindicações (v7)

A verificação de citações e a calibração de reivindicações capturam classes de erro disjuntas: a verificação captura afirmações falsas sobre fontes; a calibração captura descobertas verdadeiras montadas em generalizações não suportadas. O pipeline agora aplica ambas — o prompt do Rascunho carrega uma barreira de força de reivindicação (palavras de frequência/prioridade/finalidade como "primeiro", "único", "esmagadoramente", "apagado" exigem uma busca projetada para suportá-las, caso contrário linguagem com escopo de amostra), os leitores marcam a postura de cada fonte (incluindo disposições arguendo e não precedenciais) e relevância (apenas processual / assume a premissa / doutrina adjacente), execuções históricas recebem verificações de viés de seleção, data limite e dano/exclusão, e execuções aprofundadas adicionam uma passagem de calibração adversarial dedicada no rascunho. Uma terceira classe de erro fica entre elas: uma

…

[truncado para tradução]