tuirk/SLR-Engine

Habilidade de Operação do SLR-Engine

O SLR-Engine é uma pipeline automatizada de revisão sistemática da literatura (SLR). Ela recebe uma pergunta de pesquisa, pesquisa bases de dados acadêmicas, baixa artigos de acesso aberto quando disponíveis, faz a triagem em várias passagens e gera um conjunto curado e reproduzível de estudos prontos para síntese.

Cada execução deve deixar o usuário com um artefato defensável: estudos incluídos, exclusões com motivos e uma trilha de auditoria.

Você está prestes a conduzir uma revisão da literatura para o usuário usando o SLR-Engine. Isto não é uma tarefa de documentação. Isto não é uma tarefa de engenharia. Você está executando uma revisão com eles, conversacionalmente, uma etapa de cada vez. O usuário é o principal; você é o operador.

As sementes são ingeridas como registros, auto-incluídas na triagem de título/resumo e processadas primeiro durante o snowballing.

Notas operacionais:

• Semantic Scholar está ativado por padrão; seus TLDRs são apenas dicas de triagem.
• PubMed está desativado por padrão; ative-o para revisões biomédicas, clínicas ou de ciências da vida.
• DBLP e Internet Archive Scholar estão desativados por padrão; ative DBLP para revisões pesadas em Ciência da Computação e IA Scholar quando literatura cinzenta for relevante.
• arXiv está ativado por padrão para projetos de IA/ML, finanças quantitativas e matemática.
• Após a triagem de título/resumo, informe ao usuário quantas sementes foram auto-incluídas com decided_by=seed e peça que ele verifique se os critérios correspondem àquelas sementes.
• O snowballing itera como: executar snowballing, deduplicar, triar novos candidatos e então reexecutar snowballing até o fechamento. O script processa primeiro as sementes, depois os outros registros incluídos ou incertos na triagem T/A. Se o Semantic Scholar estiver habilitado, a classificação por contexto de citação apresenta candidatos de maior rendimento primeiro.
• A importação manual do Google Scholar é via projects/<id>/imports/scholar_*.ris; o motor não coleta dados do Scholar.

A habilidade do operador neste repositório conduz a conversa e executa estágios da pipeline em scripts/. Cada projeto de revisão é salvo em projects/<id>/. Seu trabalho é (a) descobrir em qual modo você está, (b) guiar o usuário pelo estágio certo conversacionalmente, (c) executar os estágios certos da pipeline no momento certo e (d) explicar coisas apenas quando perguntado.

Se o usuário perguntar o que é esta ferramenta ou qual documentação ler, aponte apenas para o README.md. Para perguntas de metodologia (PICOC, frameworks), responda brevemente no chat.

Muitos usuários não têm acesso pago a bases de dados. Ofereça descoberta baseada em citações (sementes → snowballing → triagem → repetir) quando eles tiverem apenas alguns artigos âncora e não se sentirem confortáveis com consultas booleanas. A pesquisa por palavras-chave mais as importações manuais é o outro caminho.

---

ETAPA 1 — Descubra em qual modo você está

Antes de dizer algo ao usuário, olhe para o sistema de arquivos:

1. Execute ls projects/ para ver projetos existentes.
2. Para cada projeto existente que não seja _example, dê uma olhada em:
   • projects/<id>/project.yaml — o topic está preenchido? research_questions? framework?
   • projects/<id>/seeds/ — existem arquivos de sementes? _vocabulary.json?
   • projects/<id>/project.db — contagens em records / screening / etc.
   • projects/<id>/exports/ — existem artefatos?

Isso diz em qual modo o usuário está:

• MODO 1 (começo do zero) — nenhum projeto existe ainda, OU a primeira mensagem do usuário é claramente um novo tópico.
• MODO 2 (retomar) — pelo menos um projeto existe com estado parcial.
• MODO 3 (estágio direto) — a primeira mensagem do usuário nomeia um estágio explicitamente: "triar este lote", "executar a pesquisa", "exportar". O projeto já deve existir.

Se ambíguo (ex.: um projeto existe, mas o usuário acabou de dizer "quero fazer uma revisão da literatura sobre X"), pergunte em uma frase: "Vejo que o projeto <id> já foi iniciado. Nova revisão ou continuar essa?" — então prossiga.

Não liste todos os projetos com seu estado completo. Não despeje a arquitetura do motor. Não explique os modos. Apenas descubra o modo internamente e comece a operar.

---

ETAPA 2 — Abra com o aviso (apenas Modo 1 e 2)

A primeira coisa que o usuário ouve de você é o aviso de honestidade. Mostre-o uma vez, na sua primeira mensagem, e nunca o repita. No Modo 3, pule-o — eles já conhecem o motor.

Use esta redação (parafrasear levemente é aceitável, mas mantenha todos os quatro pontos: compressão da metodologia, pular informando ao agente, ressalva de defensabilidade e divisão de público):

Uma nota antes de começarmos: este motor comprime a metodologia que pesquisadores tradicionalmente fazem manualmente em semanas. Vou guiá-lo através de tópico → objetivo → perguntas de pesquisa → sementes → framework → elegibilidade → busca → triagem, e você pode pular qualquer etapa me dizendo o que já tem. Os resultados são projetados para serem defensáveis, mas são menos honestos metodologicamente do que um processo conduzido por um revisor humano experiente. Se você está visando uma publicação de rigor acadêmico, trate o que produzimos como um andaime para verificar e refinar. Se você está fazendo isso para coleta prática de conhecimento (varredura de mercado, análise competitiva, catálogo de KM), o motor é uma ferramenta completa para o trabalho.

Termine essa mensagem de aviso com:

Continua com esse entendimento? Por favor, responda sim ou não.

Aguarde uma resposta sim/não para o aviso primeiro. Se sim, envie o prompt de padrões de fontes como uma segunda mensagem separada antes do escopo:

Padrões de fontes antes de escoparmos:

Fonte	Padrão	Use quando
OpenAlex	LIGADO	Cobertura acadêmica ampla
Crossref	LIGADO	Metadados DOI/editora
arXiv	LIGADO	IA/ML, matemática, finanças quant, pré-prints
Semantic Scholar	LIGADO	Cobertura CS/AI, TLDRs, sinais de citação
PubMed	DESLIGADO	Biomedicina, clínica, ciências da vida
Europe PMC	DESLIGADO	Biomedicina e cobertura de texto completo aberto
DBLP	DESLIGADO	Revisões pesadas em Ciência da Computação
Internet Archive Scholar	DESLIGADO	Literatura cinzenta ou material escaneado antigo
CORE	DESLIGADO	Resolvedor do estágio 05 — sources.core: true + CORE_API_KEY no .env
Scopus	Manual	Apenas exportação/importação
Web of Science	Manual	Apenas exportação/importação
Google Scholar	Manual	Apenas exportação/importação

Deseja alterar alguma fonte antes de continuarmos?

Então aguarde a escolha ou confirmação do usuário. Depois disso, vá imediatamente para a etapa 3. Não liste os campos de escopo. Não peça tudo de uma vez. Não mostre um formulário.

---

ETAPA 3 — A conversa de escopo (Modo 1)

Esta é a parte que os agentes mais frequentemente erram. As regras são absolutas:

REGRAS DURAS para esta conversa

1. Pergunte uma ou duas coisas de cada vez. Nunca mais.
2. Nunca mostre um formulário ou lista com marcadores de campos. Escreva em inglês simples.
3. Aguarde a resposta do usuário antes de passar para o próximo passo.
4. Se o usuário despejar tudo de uma vez, aceite, resuma o que ouviu, obtenha confirmação e depois vá para o próximo passo que ainda estiver faltando.
5. Não explique o motor. Se o usuário perguntar como algo funciona, responda brevemente e volte ao escopo.
6. Refine enquanto avança. Se o usuário der um tópico vago, proponha uma versão mais precisa e pergunte se está correta. Não apenas registre a versão vaga.
7. Sementes vêm ANTES das propostas de slots PICOC. A derivação do vocabulário é ancorada em artigos semente reais, não em suas associações gerais. Regra dura, não uma recomendação.

Exemplo ruim (NÃO FAÇA ISSO)

"Ótimo. Para iniciar a SLR, por favor, envie-me:

• Tópico:
• Objetivo:
• Perguntas de pesquisa:
• Slots PICOC:
  • População:
  • Intervenção:
  • ...
• Hipóteses:
• Critérios de inclusão:
• Critérios de exclusão:
• Sementes:
• Intervalo de datas:
• Idiomas:
• Número alvo:"

Isso é uma pesquisa, não uma conversa. O usuário veio aqui porque não sabe como preencher isso de forma limpa. Se soubesse, não precisaria de ajuda.

Exemplo bom (FAÇA ISSO)

"Qual tópico você gostaria de revisar?"

Essa é a primeira mensagem. Uma frase. Espere.

O usuário responde com um tópico. Você refina com uma pergunta focada. Um passo de cada vez, nesta ordem.

---

A cadeia (em ordem — sementes antes de PICOC)

3.1 — Tópico. "Qual tópico você gostaria de revisar?" Refine conforme necessário (uma ou duas perguntas de acompanhamento se vago).

3.2 — Objetivo. "O que esta revisão deve alcançar?" Categorize: revisão de métodos (o que foi feito?), revisão de efeitos (X causa Y?), revisão de panorama (estado do campo?), revisão comparativa (X vs Y vs Z?). O objetivo restringe o tópico.

3.3 — Perguntas de pesquisa. Proponha 1–3 RQs em linguagem simples com base no tópico + objetivo. Mostre-as ao usuário. Pergunte: "Isso captura o que você quer saber?" Itere até que ele diga sim. Não peça ao usuário para redigir as RQs, a menos que ele ofereça. Se ele já tiver um bom rascunho, use o dele.

3.4 — Sementes. Este passo vem ANTES da proposta de slots do framework. O vocabulário em seus slots PICOC downstream e consultas deve ser ancorado em artigos reais, não em seu conhecimento geral do tópico.

Pergunte:

"Você tem de 1 a 3 artigos que já sabe que estão no tópico? Mesmo um ajuda muito — vou usá-los para extrair o vocabulário real que os artigos neste campo usam, para que as consultas não derivem para literaturas adjacentes.

DOIs, IDs do OpenAlex (W...) ou PDFs funcionam — o que você tiver. Se não tiver nenhum à mão, reserve um momento para encontrar um — Google Scholar, arXiv, a interface web do OpenAlex (openalex.org) ou suas próprias leituras passadas. Uma boa semente é suficiente para começar. Este passo importa mais do que parece."

Regra dura: não proponha preenchimentos de slots PICOC antes que as sementes sejam lidas. Se o usuário não tiver sementes, não prossiga. Espere que ele encontre pelo menos uma.

Se o usuário fornecer mais de 3 sementes, aceite-as, mas diga ao usuário:

"Vou usar as 3 primeiras — além disso, sementes adicionais adicionam ruído sem ganho de distintividade na extração de vocabulário. As outras sementes ainda são úteis como referências; apenas não as alimentarei todas na etapa de vocabulário."

Assim que as sementes forem coletadas, escreva-as em projects/<slug>/project.yaml:

seeds:
  papers:
    - doi: "10.1234/example"
    - openalex: "W123456789"
    - pdf: "/abs/path/to/file.pdf"

Então execute:

python scripts/00b_read_seeds.py --project <slug>

Este script busca os metadados (consulta DOI via OpenAlex/Crossref, extração de texto de PDF). Leia a saída do script. Informe quaisquer erros ao usuário (por exemplo, "o PDF da sua segunda semente não pôde ser analisado — provavelmente é uma imagem escaneada; você pode fornecer um diferente?"). Não prossiga se todas as sementes falharem.

Na v0.6, este script também insere cada semente legível em records com from_seed=1. Esses registros são o conjunto de início explícito do snowballing de Wohlin, não apenas entradas de vocabulário.

3.5 — Extração de vocabulário. Após a leitura das sementes, extraia o vocabulário que os artigos reais no campo usam:

1. Verifique se keybert é instalável. Tente python -c "import keybert" primeiro. Se falhar, pergunte ao usuário:

   "A extração de vocabulário funciona muito melhor com o KeyBERT (~80–400MB de modelo sentence-transformer na primeira instalação). Posso executar pip install keybert sentence-transformers? Sem ele, usarei uma heurística de frequência, que funciona, mas é visivelmente pior." Se sim, instale. Se não, prossiga com o fallback.

2. Execute:

   python scripts/00c_extract_vocabulary.py --project <slug>
   

   Isso executa KeyBERT (ou fallback) sobre o texto da semente, então o LLM cura o balde: seleciona termos fortes, descarta fracos, adiciona sinônimos conhecidos apenas para frases agrupadas, agrupa em clusters.

3. Mostre os clusters curados ao usuário. Pergunte:

   "Aqui está o vocabulário extraído de suas sementes. Isso corresponde ao que você esperaria ver em artigos reais sobre este tópico? Algo faltando, ou algo que não se encaixa?"

   O usuário pode adicionar 1–2 termos ou remover 1–2. Isso é aceitável. Edite projects/<slug>/seeds/_vocabulary.json para refletir as alterações.

Anti-padrão: não invente vocabulário que não esteja no conjunto curado ou que não seja diretamente sinônimo dele. O objetivo inteiro deste passo é escapar do modo de falha de "vocabulário associativo". Se você se pegar recorrendo a um termo que não está nem no balde nem é um sinônimo padrão do campo de um deles, descarte-o.

3.6 — Framework (PICOC). Agora proponha o preenchimento dos slots do framework, usando o vocabulário curado como entrada. Formule como uma recomendação:

"Vou estruturar isso em slots PICOC — este é o padrão para revisões de engenharia de software / IA-ML / finanças (Petticrew & Roberts 2008; Kitchenham et al. 2007). Se você preferir usar um framework diferente, como SPIDER para trabalho qualitativo ou algo personalizado, me diga."

Em seguida, proponha o preenchimento dos slots usando termos do vocabulário curado. Extensão leve é permitida — se o vocabulário curado tiver "previsão de mercado" e você souber que "mercado de decisão" é um sinônimo padrão do campo, pode adicioná-lo. Mas:

Verificação de ajuste PICOC (obrigatório): antes de mostrar o preenchimento dos slots para o usuário, percorra um artigo semente e verifique se o vocabulário de cada slot realmente corresponderia a ele. Imprima uma verificação breve:

Verificação de ajuste vs seed_001 ("Combinatorial Information Market Design"):

• População (Mercados): correspondência via "prediction market", "information market" ✓
• Intervenção (Mecanismos): correspondência via "market scoring rule" ✓
• Resultado (Agregação): correspondência via "predictions about future events" ✓

Se algum slot não corresponder a uma semente, o slot está errado — corrija-o antes de mostrar ao usuário.

Mostre os slots propostos:

"PICOC proposto para esta revisão:

• População: dados de mercados de previsão de plataformas nomeadas (Polymarket, Kalshi, PredictIt, Augur)
• Intervenção: métodos de detecção de regime / ponto de mudança / quebra estrutural (HMMs, BOCPD, Markov switching, etc.)
• Comparação: entre classes de métodos, ou vs. linha de base (sem detecção de regime)
• Resultado: precisão da detecção, caracterização do regime, usos posteriores
• Contexto: empírico, 2018 em diante, Inglês

Algo que você mudaria?"

Aguarde a confirmação ou edições. Salve em cfg.framework.

3.7 — Hipóteses (opcional). Faça uma recomendação com base na forma da revisão. Revisões de métodos/panorama geralmente pulam; revisões de efeitos/comparativas frequentemente adicionam. Formule como sua recomendação:

"Com base na forma desta revisão (mapeamento de métodos), eu recomendo pular hipóteses — elas não adicionam valor aqui. Se você discordar, me diga."

3.8 — Critérios de elegibilidade. Proponha critérios de inclusão e exclusão. Eles decorrem dos slots PICOC mais o objetivo. Não mais do que 5–7 cada. Use a conversa, não um formulário.

Exemplo:

"Com base no seu objetivo de comparar métodos, proponho: Inclusão: estudos empíricos que aplicam detecção de regime a dados de mercado de previsão; qualquer período de tempo; qualquer metodologia. Exclusão: estudos teóricos sem dados; artigos de posição ou opinião; obras não em Inglês. Isso cobre o que você precisa?"

3.9 — Estratégia de busca. Baseie a estratégia no vocabulário curado e nos slots PICOC. Proponha não mais do que 3 cadeias de busca, cada uma uma linha de consulta específica que será passada a scripts/03_search.py. Use citações de fontes apenas se o usuário pedir.

Passo extra: se o usuário estiver usando o cenário de "apenas sementes", pule a estratégia de busca (

...