danepps/habilidades-de-pesquisa-jurídica

Construir Biblioteca

Popule uma coleção Zotero com fontes para um projeto. Defesa em duas camadas contra fontes fabricadas: (1) verifique cada candidato em relação a uma fonte real antes de adicionar; (2) após adicionar, execute o verificador determinístico incluso — nenhum item é enviado sem verificação. Todas as regras de autoridade global (nunca inventar uma citação; sinalizar incerteza) se aplicam durante todo o processo.

0. Etapa zero — leia toda a biblioteca antes de fazer qualquer outra coisa

Antes de definir escopo, antes de pesquisar, antes de propor um único candidato, despeje a biblioteca alvo e leia tudo:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/build-library/library_inventory.py --group <ID>   # ou --user
python3 ${CLAUDE_PLUGIN_ROOT}/skills/build-library/library_inventory.py --group <ID> --grep <termos>

Uma linha por item de nível superior: ano, PDF-ou-não, autores, título, publicação, chave do item. Uma biblioteca de 100 itens tem bem menos de 3k tokens. Não há razão orçamentária para pular isso e não há substituto. Para uma biblioteca grande (milhares de itens), salve o despejo completo em um arquivo e leia as fatias --grep relevantes mais a forma geral — mas o coordenador ainda é responsável pela verificação, e uma fatia que nunca foi pesquisada com grep não é evidência de ausência.

Esta é a etapa zero, e não parte da triagem de duplicatas, porque conhecer a biblioteca muda o que você procura. Uma execução que a pula proporá coisas que o usuário já possui, descrevendo-as como "recém-identificadas", e fará afirmações falsas sobre lacunas na coleção.

Quatro regras rígidas, cada uma de uma falha real (2026-08-01, em uma biblioteca de grupo de 105 itens):

1. Nunca delegue o inventário ou a verificação de duplicatas a um subagente. Um subagente de pesquisa relatou que o grupo continha "apenas os 13 itens listados mais um punhado de trabalhos não relacionados". Continha 105. O coordenador acreditou e criou três duplicatas. Subagentes são bons para encontrar candidatos; o coordenador é responsável por conhecer a biblioteca.
2. Trate uma descoberta negativa de um subagente como não verificada. "Verifiquei e não está lá" é exatamente a afirmação que os subagentes erram, porque a ausência é infalsificável de dentro de uma pesquisa restrita. Verifique novamente qualquer alegação de "não está na biblioteca" contra seu próprio inventário.
3. Toda adição passa pela verificação, incluindo as tardias. Duas das três duplicatas foram adicionadas bem no final da sessão, a partir de notas de rodapé em um artigo que acabara de ser lido — fora do pipeline principal, então pularam a triagem completamente. Nenhum candidato é pequeno ou tardio demais para ser verificado; faça grep no inventário que você já tem.
4. Passe o inventário adiante. Qualquer subagente solicitado a encontrar fontes recebe a lista real (ou uma fatia filtrada) colada em seu prompt — nunca uma instrução para verificar por conta própria.

A biblioteca também é evidência. Quando a tarefa é "o que está faltando", o que o usuário já possui diz o que é importante para ele e muitas vezes reformula a resposta. Na execução que motivou esta regra, a biblioteca do usuário acabou por conter uma prateleira profunda de estudos de direito penal exatamente sobre os tópicos que o memorando acabara de descrever como não abordados — o que mudou a conclusão de "ninguém escreveu sobre isso" para "essas duas literaturas não se citam mutuamente". Leia o inventário pelo que ele diz sobre o projeto, não apenas para correspondência de duplicatas.

1. Encanação Zotero

As ferramentas MCP zotero / zotero-group são somente leitura (boas para verificações de duplicatas e pesquisa). Todas as gravações passam pela API Web do Zotero v3 com a chave da entrada zotero em ~/.claude.json (env.ZOTERO_API_KEY; verificada para ter acesso de gravação à biblioteca pessoal, <USER_ID>, e quaisquer bibliotecas de grupo que você usar).

• Coleções: GET /users/<USER_ID>/collections?limit=100 → encontre a chave alvo; crie com POST /collections se o usuário quiser uma nova (confirme o nome primeiro).
• Verificação de duplicatas — inventário primeiro (§0), triagem da lista de candidatos (§2a), proteção antes de adicionar: leia toda a biblioteca com antecedência (§0); remova duplicatas da lista de candidatos antes de qualquer verificação ou trabalho de PDF (§2a); depois mantenha uma verificação final leve logo antes do POST /items como proteção — ela pega itens adicionados anteriormente na mesma execução e colisões de edição exata que as triagens anteriores perdem. Para consultas únicas no meio da execução, library_inventory.py --grep <termos> supera mcp__zotero__zotero_search_items, porque pesquisa a lista que você já possui em vez de emitir uma nova consulta restrita.
• Criar itens: POST /users/<USER_ID>/items com uma matriz JSON (≤50/solicitação). Verifique os mapas success/failed da resposta. Obtenha um modelo em branco de GET https://api.zotero.org/items/new?itemType=book quando não tiver certeza dos campos.
• Convenções: ilustradores/ créditos "com" → criadores contributor mais uma nota extra (os livros do Zotero não têm função de ilustrador); editores → editor; coloque a editora/gráfica real da edição (por exemplo, Sentinel, não "Penguin"); data de publicação completa quando verificada, ano caso contrário; ISBN sempre para livros, DOI sempre para artigos.

1a. Metadados de artigos de law review — correções para defeitos do Zotero Connector (autor, 2026-07-16)

O Claude cria itens via a API Web, então pode acertar onde o Zotero Connector do usuário consistentemente erra. Aplique a cada artigo de law review adicionado; Hein (§4a) mostra os dados corretos, então pegue os campos de lá.

1. Artigo inicial "The"/"A"/"An": mantenha o artigo na posição natural inicial — título The Common Law, nunca o inverso de classificação do Connector Common Law, The.
2. Ano = o ano do fascículo, não o intervalo do volume. O Connector frequentemente pega o intervalo de datas do volume inteiro; use o ano do fascículo específico, que a citação do Hein fornece.
3. Ponto de interrogação final: preserve-o — Are Judges Political?, não Are Judges Political.
4. Itálicos em títulos: o campo de título do Zotero aceita HTML embutido — envolva nomes de casos (e outros termos em itálico do Bluebook) em <i>…</i>, por exemplo, The Real Meaning of <i>Erie</i> ou Rethinking <i>Chevron</i> Deference. O Zotero renderiza e exporta estes como itálico (este é o <i>nome do caso</i> que o usuário adiciona manualmente).
5. Remova rótulos de tipo de peça/simpósio anexados do título — mas preserve designações reais do Bluebook em extra. O Connector anexa designações ao título — Essay, Comment, Note, Foreword, Book Review, Symposium: <nome>, etc. Mantenha apenas o título real do artigo conforme ele encabeça a peça / aparece na citação Bluebook. Se não tiver certeza se o texto final é um subtítulo real versus um rótulo anexado, verifique a primeira página.
   • Notas e comentários de estudantes (e outras designações que o Bluebook imprime entre o autor e o título — Recent Development, Essay, Foreword, Book Review, etc.): não descarte apenas o rótulo. Registre-o no campo extra do item como uma linha genre: — genre: Note para uma nota de estudante, genre: Comment para um comentário (em maiúsculas e minúsculas; o estilo coloca em maiúsculas de qualquer forma, mas armazene de forma limpa). O estilo Bluebook então o insere no lugar certo (Jane Doe, Note, <i>Title</i>, 120 Harv. L. Rev. 1627 (2007)). Remova-o do título como acima e adicione a linha genre: — os dois andam juntos para essas peças.
   • Notas de estudantes anônimas (sem autor listado): deixe os criadores vazios e ainda defina genre: Note. Se o campo extra já carregar outras linhas (por exemplo, Verified-URL:), adicione genre: Note em sua própria nova linha — não as substitua.
6. Sufixos ("Jr.", "III", "Sr."): O Zotero não tem campo de sufixo — codifique o sufixo no campo Nome, anexado ao nome próprio com uma vírgula e sem espaço (lastName permanece apenas o sobrenome; nunca anexe o sufixo ao sobrenome ou adicione um segundo autor). Um ! inicial no sufixo controla se uma vírgula é renderizada antes dele (marcação citeproc-js, conforme o autor):
   • "John Smith Jr." (sem vírgula) → firstName: "John,Jr.", lastName: "Smith"
   • "John Smith, Jr." (com vírgula) → firstName: "John,!Jr.", lastName: "Smith" O nome próprio, incluindo qualquer nome do meio/inicial, vai antes da vírgula (por exemplo, John B.,Jr.). Mesmo mecanismo para numerais/outros sufixos — John,III vs John,!III, John,Sr. etc. Corresponda a qualquer forma de vírgula que o autor/fonte use.
7. Abreviatura do Periódico (Bluebook, maiúsculas e minúsculas): sempre preencha o campo journalAbbreviation do Zotero ("Journal Abbr" na interface) com a abreviatura Bluebook do periódico (Tabela T13) em maiúsculas e minúsculas normais — Colum. L. Rev., Harv. L. Rev., Nw. U. L. Rev., J. Sup. Ct. Hist., Sup. Ct. Rev. — NÃO EM CAIXA ALTA. O estilo de citação aplica as versaletes ele mesmo, então armazene Colum. L. Rev., nunca COLUM. L. REV. O nome completo permanece em publicationTitle; a abreviatura vai em journalAbbreviation. A exibição da citação do Hein a renderiza em caixa alta/versaletes ("62 COLUM. L. REV. 633") — use-a para a redação, mas converta para maiúsculas e minúsculas; para um periódico desconhecido, verifique a forma T13 em vez de adivinhar. Para um companheiro/suplemento online, anexe o nome do suplemento abreviado conforme o Bluebook — Forum → F. (por exemplo, Harv. L. Rev. F.), enquanto Colloquy não tem forma abreviada (Nw. U. L. Rev. Colloquy). Exceções conhecidas específicas de nomes (não "corrija" estas): California Law Review → Calif. L. Rev. (não Cal., mesmo que Califórnia seja Cal. em repositórios e em outros lugares). A peculiaridade Calif. é específica daquele periódico — contraste Southern California Law Review → S. Cal. L. Rev., onde Califórnia assume o Cal. usual.

2. Encontrar candidatos

Defina o escopo com o usuário se a solicitação for aberta (quais juízes/estudiosos/época; apenas livros ou artigos também; livros comerciais vs. manuais/tratados — sinalize julgamentos de valor no relatório em vez de decidir silenciosamente). Faça isso após §0, nunca antes — o inventário informa o que o usuário já possui, o que muda o que vale a pena procurar.

Pesquise em paralelo: WebSearch; Open Library (search.json?title=&author= supera q= simples); infoboxes da Wikipedia (/w/index.php?title=<página>&action=raw, grep na infobox) para editora/data/ISBN de livros notáveis; páginas de editoras. Para estudos jurídicos, HeinOnline (§4). A API do Google Books é uma cota anônima compartilhada que muitas vezes é esgotada — trate-a como bônus, não como espinha dorsal.

2a. Triar candidatos contra a biblioteca

Com o inventário em mãos, remova duplicatas da lista de candidatos antes do caro pipeline de verificar → baixar → adicionar (§3+). Verificar metadados e baixar PDFs (cadeias curl do Hein, attach_pdf.py) é a parte cara de uma execução; fazê-lo para uma fonte já na biblioteca é puro desperdício.

1. Corresponda cada candidato ao inventário em autor + ano primeiro, título depois — títulos variam (subtítulos, "Parte I", artigos invertidos por classificação, entidades HTML), mas colisões de autor-mais-ano são um gatilho confiável para uma olhada mais de perto.
2. Descarte correspondências claras (mesmo trabalho já presente) — não verifique ou baixe.
3. Sinalize, não descarte silenciosamente, correspondências próximas ambíguas (mesmo autor, título semelhante-mas-não-idêntico; uma edição/impressão diferente; artigo vs. seu companheiro online). Às vezes você só define a edição exata durante a verificação, então leve uma candidata genuína adiante e anote-a no relatório em vez de descartá-la por suposição.

Apenas os sobreviventes passam por §3. A proteção de pré-adição em §1 então pega duplicatas dentro da execução e colisões de edição exata.

Se você criar uma duplicata, mescle antes de excluir. O item pré-existente pode conter o PDF, anotações, tags e associações de coleção do usuário; o seu novo pode conter melhores metadados. Faça PATCH dos campos bons no item existente, então DELETE o seu. Nunca exclua o registro mais antigo. (Na limpeza de 2026-08-01, isso recuperou um defeito real: o item Kahan do usuário tinha a string "10.2307" sentada em seu campo issue e nenhum DOI.)

Regra de fluxo de trabalho (autor, 2026-07-16): resolva toda fonte de law review através do HeinOnline. Hein é o caminho autônomo limpo (§4a: autenticado por IP, sem barreira de bot, sem portal). Uma fonte que Hein não carrega e que nenhum repositório aberto serve é relatada como tal (§5) em vez de adicionada sem um registro verificado.

3. Verificar → adicionar → verificação determinística (innegociável)

Antes de adicionar: todo campo que você escreve deve vir de uma fonte obtida — um registro de edição do Open Library (/isbn/<isbn>.json), uma página de editora, uma infobox da Wikipedia, uma listagem de livraria. Nunca escreva um ISBN/data/editora plausível da memória. Cuidado com registros de edição OL corrompidos (um livro errado atrás de um ISBN acontece); verifique qualquer surpresa contra uma segunda fonte.

Após adicionar, execute o verificador incluso exatamente no que caiu no Zotero:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/build-library/check_source.py --collection <CHAVE>   # coleção inteira
python3 ${CLAUDE_PLUGIN_ROOT}/skills/build-library/check_source.py --keys K1,K2,K3      # apenas novos itens

Ele resolve o ISBN de cada item em cinco catálogos independentes (edição do Open Library + índice de pesquisa, Google Books, Harvard Library, Library of Congress) ou seu DOI no Crossref, e faz comparação de strings normalizada de título/autores/ano. Vereditos: PASS, FAIL (resolvido, mas incompatível), UNRESOLVED (identificador não encontrado em nenhum catálogo verificado — um aviso para re-verificar, não prova de fabricação: catálogos são incompletos e às vezes estão fora do ar), BAD_ISBN (checksum), NO_IDENTIFIER. --stdin aceita uma matriz JSON de itens em formato Zotero para pré-verificar candidatos antes de adicionar.

Cada item que você adicionou deve terminar como PASS. Manual para não-PASS:

• FAIL em apenas uma fonte → geralmente corrupção de catálogo; o verificador já tenta as outras fontes, então um FAIL persistente geralmente significa que seus dados estão errados — re-verifique contra uma página de autoridade aberta e faça PATCH do item (envie If-Unmodified-Since-Version: <versão do item>). Se a página aberta confirmar seus dados, registre-o como Verified-URL: e diga isso no relatório em vez de "corrigir" metadados corretos para corresponder a um catálogo.
• UNRESOLVED/muito recente para catálogos (livros <~1 ano) → adicione uma página de autoridade buscável como Verified-URL: no campo extra e relate a limitação ao usuário.
• NO_IDENTIFIER → você esqueceu de incluir o ISBN/DOI; adicione-o e execute novamente a verificação.
• BAD_ISBN → seu ISBN tem um dígito de verificação inválido; verifique seu manuscrito contra o que você realmente obteve.

Não há aprovações manuais; UNRESOLVED requer uma URL verificada e uma explicação ao usuário. Uma fonte que ainda não existe não é adicionada. (Ninguém sabe quanta fabricação essa regra evitou, mas ela pegou três itens ruins apenas na primeira semana de uso, incluindo um falso New York Times best-seller de um autor real com um ISBN plausível que nenhum catálogo tinha. O verificador não é discricionário; é o piso.)