research-plan

Pesquisa → plan.md + arquivo de fontes

O orquestrador de um conjunto de três skills:

• source-triage: encontrar fontes e classificar acesso, alcance, integridade e nota antes de ler.
• research-plan (este skill): ler o que é acessível, depois escrever o plano e o arquivo de fontes.
• evidence-check: uma auditoria independente de que cada afirmação é real e apoiada.

Se um skill irmão estiver faltando, execute seus passos manualmente a partir destes resumos. O verificador determinístico está incluído neste skill: python3 <pasta deste skill>/scripts/research_checks.py. É Python da biblioteca padrão que roda em seu próprio sandbox de código (texto de PDF precisa de pypdf; pip install pypdf lá se estiver faltando). Use-o sempre que uma verificação determinística for nomeada. Somente se nenhuma execução de código estiver disponível, faça essas verificações manualmente e informe isso.

Saídas (nomes fixos)

research/<slug-do-topico>/plan.md
research/<slug-do-topico>/sources__<slug-do-topico>__<AAAA-MM-DD>.md   ← visão humana
research/<slug-do-topico>/ledger.md                                    ← estado de trabalho, escrito conforme avança
research/<slug-do-topico>/notes/<chave-de-citacao>.md                  ← notas por fonte
research/<slug-do-topico>/notes/raw/<chave-de-citacao>.txt             ← texto completo bruto (API XML/texto de PDF), capaz de transcrição literal
research/<slug-do-topico>/claims.json                                  ← afirmações apoiadas + citações, para verificação

• <slug-do-topico>: 3–6 palavras específicas, hifenizadas em minúsculas (amido-frutano-engenharia-plantas).
• Nunca sobrescreva uma execução anterior. Mesmo tópico: novo arquivo de fontes datado + entrada de changelog. Novo ângulo: novo slug.
• Trabalhe na pasta conectada do usuário, se houver, caso contrário, no diretório de trabalho. Envie ambos os arquivos principais ao final.

Modos

• auto (padrão): sem pausas; liste suas escolhas ao final. step: pare em cada ◆.
• quick: mantenha 8–15 fontes. Leituras completas de até 5 fontes principais; outras sections: (resumo + resultados + discussão). Contra-evidências: no máximo 3 pesquisas. Snowball opcional.
• deep: 25+ fontes, snowballing, explorações paralelas, leituras completas de todas as fontes A/B.
• update: o usuário baixou arquivos ou pediu para atualizar → Fase 6.
• Restrições rígidas na solicitação (uma rubrica que precisa de 2 capítulos de livro, um limite de palavras, um banco de dados obrigatório) são requisitos, não sugestões. Atenda-os com fontes verificadas, ou diga claramente qual delas não foi atendida.

Fase 0 — Enquadramento

Uma mensagem:

• o objetivo do plano e para que serve (agente / skill / MCP / relatório / experimento / decisão);
• escopo, anos, profundidade e modo;
• restrições rígidas;
• 2–6 eixos MECE (subperguntas não sobrepostas).

Crie uma lista de tarefas: Enquadrar → Triar → Ler → Sintetizar → Escrever → Verificar. Se não existir ferramenta de tarefas, mantenha a lista no topo de research/<slug>/run-notes.md. ◆ Ponto de verificação: eixos + escopo.

Fase 1 — Triagem (executar source-triage)

Biblioteca primeiro → descobrir → integridade de tudo que você nomear → acesso + alcance → nota / função / ⭐.

O ledger é escrito conforme você avança. Acrescente cada pesquisa e cada fonte classificada imediatamente; o contexto pode ser perdido no meio da execução, e o arquivo ledger é o que sobrevive.

No modo profundo com subagentes, envie um explorador por eixo em paralelo. Cada explorador:

• usa ≤15 chamadas de ferramenta;
• escreve notes/<eixo>.md com seções Conclusão · Achados citados (com links) · Inferências · Lacunas;
• anexa seus candidatos ao ledger.

Sem subagentes, execute os eixos em sequência. ◆ Ponto de verificação: contagens por classe de acesso + lista de ⭐.

Fase 2 — Leitura

• Leia fontes leggível/retida, da maior nota primeiro. Prefira rotas brutas (XML Europe PMC via shell, texto de PDF) e salve o texto em notes/raw/<chave-de-citacao>.txt.
• Uma leitura WebFetch é read: full (extracted). Use-a para entendimento, mas afirmações baseadas nela recebem ⚠ extracted e nunca são "apoiadas" por uma citação.
• Para textos longos, leia em partes até chegar à lista de referências. O modo rápido permite leituras sections:; rotule-as.
• Defina read em cada linha do ledger: full · sections:<quais> · abstract · metadata.
• Por fonte, notes/<chave-de-citacao>.md contém:
  • POR QUE (problema);
  • COMO (método, dados);
  • O QUE (achados: números copiados exatamente, com localizador de seção/página);
  • LIMITES, cada um marcado autor-declarado (com localizador) ou minha-inferência. Sem texto completo: limites: não avaliado (leitura: abstract).
• Quando uma frase carregar uma afirmação no plano, copie uma citação literal de ≥40 caracteres do texto bruto para claims.json: {"id","claim","source":"notes/raw/<chave-de-citacao>.txt","quote","locator"}.
• Nunca preencha uma nota de memória. "Não está na parte que li" é uma resposta válida.

Fase 3 — Síntese

• Matriz de evidências: fontes × temas (apoia / contradiz / silencia). Agrupe por tema, nunca fonte por fonte.
• Convergência (≥3 concordam) · divergência (explique por método, população ou época) · silêncio (<2 fontes: uma lacuna).
• Contagem independente: "4 estudos (2 independentes)". Um conjunto de dados, coorte, equipe ou ensaio compartilhado conta uma vez.
• Passagem de contra-evidências: para achados principais, pesquise nulos, replicações fracassadas e críticas. Registre os termos mesmo quando nada aparecer. Modo rápido: no máximo 3 pesquisas.
• Alegações negativas ("ninguém fez X") carregam as pesquisas por trás delas, limitadas ao que foi pesquisado.
• Verificação de contribuição: o que o usuário pode fazer com este plano que não podia antes? Qual ⭐ download mudaria mais?
• Passagem de advogado do diabo: o contra-argumento mais forte, a escolha seletiva de evidências e uma premissa não questionada. Não descarte uma objeção porque é inconveniente.

Fase 4 — Escrever os arquivos

plan.md

• Cabeçalho: objetivo · para que serve · escopo · data · link para o arquivo de fontes · Base de evidências: N completos (bruto) · N completos (extraído) · N seções · N resumo · N metadados.
• Corpo: o que a solicitação precisar.
• Citações: <sup>[3](sources__<slug>__<data>.md#s3)</sup>, numeradas na ordem de primeiro uso.
• Bandeiras após uma citação:
  • ⚠ apenas-resumo: apenas o resumo foi lido;
  • ⚠ apenas-metadados: apenas título/veículo conhecidos;
  • ⚠ extraído: lido via WebFetch, portanto nenhuma verificação literal é possível;
  • ⚠ preprint.
• Finalizar com: Perguntas em aberto · O que os ⭐ downloads desbloqueariam · Restrições não atendidas (se houver) · Changelog.

sources____.md

# Fontes — <Título legível do tópico> (<data>)
Plano: [plan.md](./plan.md) · Pergunta: <uma linha> · Modo: <quick|deep> · Pesquisado: <bases de dados + datas>
Contagens: N total · ⭐ X · leggível R · livre-mas-bloqueado B · paywalled P · não-artigo W · excluído E     (total = cada linha do ledger)
Base de evidências: <mesma divisão do plan.md>

## ⭐ 1. Baixe estes para contexto local
| # | Fonte | Tipo | Nota | Acesso · Licença | Por que é importante para <o que está sendo construído> | Como obter | Salvar como | Redistribuir |

## 2. Abertas & leggíveis (destiladas no plano)
### <Tema A>
<a id="s1"></a>**[1]** Autores (Ano). [Título](URL). *Periódico / Título do livro, páginas*. [DOI](https://doi.org/…) — `gold · CC-BY` · `leggível:europepmc-xml` · leitura: full · Nota A · evidência
(um preprint adiciona um rótulo `` `preprint` `` a esta linha; o verificador então exige `⚠ preprint` em suas citações)
- POR QUE … · COMO … · O QUE … · LIMITES …

## 3. Livres mas bloqueadas para agentes de IA (abra você mesmo)
Entrada + o bloqueio observado + link direto + qualquer cópia verde.

## 4. Paywalled
Entrada + link de cópia verde ou "nenhuma encontrada" + a conclusão em nível de resumo, se usada.

## 5. Fontes não-artigo
Por tipo, nível T1–T5. Literatura cinzenta: URL + data de acesso + link de snapshot.

## 6. Excluídos (e por quê)
Um marcador por registro excluído, começando com **Excluído:** <motivo>.

## 7. Registro de pesquisa e relatório de rota de acesso

Regras:

• Cada entrada tem uma âncora <a id="sN"> correspondente à numeração do plano.
• Cada URL é um link [texto](URL), inclusive nas linhas de cabeçalho.
• Linhas ⭐ apontam para o número da entrada principal.
• Agrupe por classe de acesso, depois por tema.

Fase 5 — Verificar, depois entregar

1. Verificações determinísticas: execute python3 <pasta deste skill>/scripts/research_checks.py all research/<slug>/. Corrija todos os erros (âncoras faltando, bandeiras ⚠ faltando, incompatibilidades de contagem, vocabulário, citações não na fonte) e reexecute até passar.
2. Verificação de evidências: execute evidence-check.
   • Com subagentes: em um novo, recebendo apenas os arquivos.
   • Sem: uma verificação na mesma sessão que releia todos os arquivos do disco e não use memória de tê-los escrito. Rotule-a como mesma-sessão (não independente) e sugira que o usuário execute evidence-check em um novo chat antes de confiar nela.
3. Abra 3 links por classe de acesso. Um 403/429 de um editor não prova nada; informe isso.

Entregue ambos os arquivos com uma linha sobre:

• o título do plano;
• a contagem de ⭐;
• quantas fontes precisam de download manual;
• restrições não atendidas.

No modo auto, também liste suas escolhas (eixos, anos, bases de dados, filtros, limites).

Fase 6 — Atualização (após o usuário baixar)

1. Corresponda os arquivos na pasta aos nomes Salvar como.
2. Valide-os (python3 <pasta deste skill>/scripts/research_checks.py pdf <arquivos>).
3. Leia cada um, salve seu texto bruto e defina retida: usuário e leitura: full.
4. Reclassifique, removendo notas ? provisórias.
5. Transforme bandeiras ⚠ em afirmações apoiadas com citações, ou reescreva as afirmações que o novo texto contradiz.
6. Reexecute a Fase 5 nas seções alteradas.
7. Escreva um novo arquivo de fontes datado e adicione uma entrada de changelog.

Bandeiras vermelhas

Pensamento	Realidade
"Vou verificar o acesso depois de ler"	Trie primeiro, ou resumos paywalled moldarão silenciosamente o plano.
"É OA, então posso ler"	Teste a rota. Artigos OA foram bloqueados em testes.
"WebFetch me deu o texto"	Deu uma extração do modelo. Use para leitura, nunca para citações.
"Conheço este artigo / capítulo"	Testes produziram títulos errados, livros errados e um artigo inexistente de memória. Verifique primeiro.
"O DOI resolve, então o capítulo está correto"	Verifique também o título do livro e as páginas.
"Bloqueado, vou tentar um espelho"	Nunca. Encontre uma cópia verde legítima, caso contrário liste para o usuário.
"Vou escrever o ledger no final"	Um reset de contexto o apagará. Escreva conforme avança.
"Três estudos concordam"	Conte estudos independentes; pesquise os que foram na direção oposta.