wiki-ingest

O que wiki-ingest faz?

Implementa o padrão de ingestão LLM-wiki para uma base de conhecimento científico. Cada artigo ingerido cria conhecimento rastreável e cumulativo, não apenas uma anotação isolada.

Antes da primeira ingestão, leia docs/GOTCHAS.md no kit (pegadinhas operacionais para ingestão, síntese e lint).

Modos

• padrão (ingestão): /wiki-ingest <artigo> cria ou atualiza a anotação do artigo e propaga para conceitos e métodos (Fluxo de Trabalho Padrão abaixo).
• modo de verificação: /wiki-ingest verify:<AnotacaoArtigo> reverifica uma anotação existente em relação ao texto completo e relata diferenças sem regenerar ou sobrescrever nada (consulte references/VERIFY-DIFF-MODE.md). Somente leitura, a menos que o usuário confirme cada edição.

Papel e Limites

Faz: cria ou atualiza anotações de artigos, propaga para anotações de conceitos e métodos, atualiza o índice e o registro, relata cada alteração.

NÃO faz: inventa citações, cria anotações de conceitos para conceitos de uso único ou escreve em um banco de dados. Todas as gravações passam pelas ferramentas de arquivo do host (Ler/Escrever/Editar).

Onde as coisas ficam

Os caminhos vêm de wiki.config.json (raiz do vault, raiz do wiki, nomes de pastas, idioma, limites). Padrões:

<raiz_do_vault>/
  <raiz_do_wiki>/            # padrão: wiki/
    papers/  concepts/  methods/  books/  fields/  debates/
    WIKI_SCHEMA.md        # contratos de frontmatter, nomenclatura, taxonomia, protocolo de ingestão
    index.md  log.md
  templates/              # paper.md, concept.md, method.md, book.md, chapter.md, submoc.md, synthesis.md

<kit> abaixo significa o checkout do science-wiki-kit que contém tools/ (seal.py, pmc_tables.py). Seu caminho é a chave kit_dir do wiki.config.json, escrito pelo instalador; se estiver faltando, fica duas pastas acima do diretório desta skill quando a skill está vinculada ao checkout.

Sempre leia WIKI_SCHEMA.md antes de começar. Ele define os contratos de frontmatter, as regras de nomenclatura e a taxonomia de campo deste wiki.

Skills relacionadas

• wiki-lint: compartilha wiki.config.json (o mapa de campo kebab-case para Título em Caixa Alta usado nas atualizações de índice). Execute-o após cada ingestão para verificar se não houve deriva.
• wiki-ingest-book: skill complementar para livros e capítulos. As mesmas regras de status e roteamento de índice se aplicam.
• wiki-synthesize: consome as anotações que esta skill produz.

Decisão de status inicial (aplicada a cada nova anotação)

Defina o status deliberadamente. Não deixe o padrão do template. N abaixo é min_distinct_sources_for_final na configuração (padrão 2).

Tipo de anotação	Condição	status inicial
Artigo	Resumo + pelo menos 2 descobertas com fonte extraídas	read
Artigo	Apenas metadados DOI/título, sem texto completo	stub + "> [!warning] Stub: ingestão pendente." callout
Conceito	Pelo menos 2 descobertas com fonte de N ou mais trabalhos fonte distintos	final
Conceito	Pelo menos 2 descobertas com fonte, todas de um único trabalho fonte	draft (síntese de fonte única)
Conceito	Definição + 1 descoberta com fonte	draft
Conceito	Apenas definição, sem Descobertas Chave	stub + "> [!warning] Stub: nenhuma descoberta com fonte ainda." callout
Método	Definição + N ou mais trabalhos fonte distintos em "Artigos que Usam Este Método"	final
Método	Definição e apenas 1 trabalho fonte	draft (fonte única)
Método	Definição, mas sem citações de fonte	draft
Método	Apenas esqueleto	stub

A promoção para final requer N trabalhos fonte DISTINTOS. "Distinto" conta artigos ou livros independentes: uma anotação pai de livro e suas próprias anotações de capítulo (Autor_2025 + Autor_2025_Cap01 + Autor_2025_Cap02) colapsam em um trabalho, assim como vários capítulos do mesmo livro. Uma única fonte rica (revisão sistemática, capítulo de livro-texto) pode criar um conceito e gerar várias descobertas, mas a anotação permanece draft até que uma segunda fonte independente a corrobore. Ao adicionar uma descoberta a uma anotação draft, conte os trabalhos distintos após a edição, promova apenas se a contagem atingir N e registre a promoção no relatório de ingestão. Anotações draft de fonte única carregam uma breve linha "síntese de fonte única, corrobore quando uma 2ª fonte for ingerida" no corpo.

Fluxo de Trabalho Padrão

1. Ler esquema

Leia WIKI_SCHEMA.md.

2. Resolver a fonte do artigo

Tente em ordem, usando o que seu ambiente fornecer:

• Gerenciador de referências (Zotero MCP é o adaptador suportado): pesquise, depois metadados, depois texto completo. Sequência e pegadinhas de pesquisa em references/INGEST-WORKFLOW.md.
• Tabelas XML do editor (acesso aberto no PMC): se o DOI tiver um PMCID, as tabelas podem ser extraídas célula por célula do Europe PMC JATS, independentemente da camada de texto do PDF: python <kit>/tools/pmc_tables.py <DOI> --out _temp/<stem>_pmc.md --body (saída 2 significa sem PMCID). Verifique os números das tabelas em relação ao JATS antes de abrir a imagem da página; em uma discrepância JATS versus PDF, o PDF impresso vence e a discrepância é anotada. Sem PMCID: use o PDF.
• PubMed MCP (artigo não no gerenciador de referências): pesquise por palavras-chave, depois busque pelo PMID (um DOI pode retornar um full_text vazio). Armazene o PMID no campo notes: da anotação do artigo. Use apenas para artigos biomédicos e após o usuário confirmar que não está em sua biblioteca.
• Apenas DOI: anote-o; não fabrique metadados.
• Artigo web (HTML/URL de acesso aberto): converta para markdown limpo primeiro com uma ferramenta web-para-markdown (por exemplo, a skill defuddle), depois trate a saída como resumo e corpo. Use a URL como fonte de citação quando não houver DOI.
• Manual: o usuário cola resumo ou texto. Extraia metadados e sinalize o que é desconhecido.

Onde o PDF vive é importante: a anotação nunca deve citar uma pasta de trabalho (Downloads/, um diretório temporário) que será limpa. Organize o PDF no local da biblioteca que seu grupo usa antes de escrever a anotação e registre-o em source_verification. Se o artigo não estiver na biblioteca, ou a coleção correta não estiver clara, pergunte ao usuário antes de mover qualquer coisa.

3. Determinar o nome do arquivo da anotação do artigo

Formato: PrimeiroAutor_Ano_PalavraChave.md

• PrimeiroAutor = sobrenome do primeiro autor (apenas ASCII, sem acentos, sem espaços)
• Ano = 4 dígitos
• PalavraChave = descritor de 1 a 3 palavras (CamelCase ou underscores, sem espaços)
• Exemplo: Smith_2023_Eccentric_Training.md

Verificação de duplicata e identidade (execute antes de qualquer gravação; protege contra perda silenciosa de dados):

1. Confirme a existência com uma pesquisa de conteúdo pelo nome base, ou test -f "<wiki_root>/papers/{filename}.md". NÃO confie em um único glob retornando "nenhum arquivo encontrado": ferramentas de glob de arquivo já retornaram falsos negativos para anotações que existiam, e um Write cego depois sobrescreveria uma anotação totalmente propagada. Se Write der erro com "Arquivo ainda não foi lido", isso é prova de que a anotação existe: leia-a e atualize no lugar, nunca reescreva do zero.
2. Se a anotação existente for status: stub, não presuma que é o mesmo artigo. Stubs criados a partir do contexto de citação de outro artigo carregam metadados provisórios e às vezes são um artigo diferente (ano errado, artigo versus capítulo de livro, dois artigos irmãos confundidos). Resolva a fonte real primeiro e compare autores, ano e periódico tanto com o stub quanto com a lista de referências da anotação citante. Se for um artigo diferente, ingira-o como uma NOVA anotação e mantenha ou melhore o stub.
3. Se confirmado como o mesmo artigo, atualize no lugar; nunca crie uma duplicata. O nome do arquivo pode legitimamente mudar para uma palavra-chave mais descritiva depois que você tiver o texto completo. Se for o caso, religue cada [[NomeAntigo]] e exclua o stub órfão, depois execute wiki-lint novamente para confirmar que não restaram links quebrados.
4. Guarda de identidade de citekey. Duas anotações para o mesmo artigo podem ter nomes de arquivo diferentes, portanto, uma sondagem limpa do nome base não prova nada sobre identidade. Depois que o gerenciador de referências resolver o item, pesquise em papers/ pela citekey exata que você está prestes a escrever (grep -l '^citekey: "\?{citekey}"\?$' papers/*.md). Um acerto em um nome de arquivo diferente significa que o artigo já foi ingerido: atualize essa anotação. Correspondência exata de string, sem falsos positivos.

4. Criar ou atualizar a anotação do artigo

Escreva <wiki_root>/papers/{filename}.md a partir de templates/paper.md. Preencha cada campo de frontmatter com os metadados resolvidos. Defina last_verified para a data de hoje (a ingestão é um evento de verificação). Atribua research_lines a partir dos slugs de taxonomia em WIKI_SCHEMA.md.

5. Extrair e avaliar

Uma passada sobre resumo, resultados e discussão, fazendo tudo de uma vez:

• Identifique 3 a 8 conceitos de domínio (constructos empíricos, variáveis) e 1 a 4 métodos primários. Heurísticas em references/INGEST-WORKFLOW.md.
• Classifique evidence_level: o desenho do estudo, a partir do vocabulário controlado em WIKI_SCHEMA.md (SR-MA, RCT, cohort, ...). Este é o eixo do desenho que a camada de síntese viva pondera. O eixo da qualidade da medição permanece em linha em cada descoberta quando relevante ((MRI), (estimativa antropométrica)), nunca no frontmatter.
• Roteamento de linha de pesquisa: corresponda o artigo às linhas de pesquisa em WIKI_SCHEMA.md. Se o conteúdo relevante não tiver uma linha correspondente, adicione uma ao esquema antes de propagar (adicione um par slug + rótulo; nunca renomeie ou remova linhas existentes). Se limítrofe, use a linha mais próxima e sinalize no relatório.
• Roteamento de conceito versus método: descobertas empíricas vão para concepts/; ferramentas estatísticas, desenhos de estudo e protocolos de medição vão para methods/. Decida aqui.
• Atalho puramente metodológico: se o artigo não fizer alegações empíricas, pule o passo 6 e vá para o passo 7.

5b. Tabela de evidências, antes de qualquer propagação

Para cada descoberta que chegará a uma anotação em concepts/ ou methods/ (incluindo uma alegação em "Artigos que Usam Este Método"), escreva uma linha em um arquivo temporário (nunca no wiki):

| Anotação alvo | Descoberta, como será escrita | Citação literal da fonte | Página (PDF / impresso) | Seção, tabela ou figura |

• A fonte é o PDF (ou o JATS para células de tabela). Apenas resumo ou sem PDF: marque a descoberta apenas resumo em seu texto e informe no relatório.
• Cada específico precisa de sua citação: cada figura, população, dispositivo, mecanismo, entidade nomeada e verbo de força. Divida a descoberta ou use várias citações até que tudo seja coberto.
• Leia o parágrafo inteiro ou linha da tabela ao redor do acerto, não apenas o número correspondente.
• Tabelas, figuras, sinais, ICs e ±: renderize a página e olhe para ela. A extração de texto é uma hipótese, a imagem é a prova. Alguns PDFs perdem o sinal de menos na camada de texto (-5.2% é extraído como 25.2%), produzindo um número falso plausível.
• Ausência precisa de uma pesquisa positiva, tanto no texto com layout quanto no texto sem layout e com variantes de ortografia, antes de qualquer coisa ser escrita como "o artigo não...".

5c. Verifique a tabela antes de escrever

Leia cada linha em relação à sua citação antes que qualquer anotação seja tocada. Se um subagente extraiu o artigo, releia cada linha no PDF, não apenas as linhas com uma figura ou sinal. Classes de defeito a julgar: inferência além da fonte, erro de atribuição, número errado, hedge perdido, superlativo não suportado, entidade errada, detalhe inventado, omissão.

• Uma linha cuja citação não a suporta é reformulada para o que a citação diz, ou descartada. A anotação fonte não é evidência: ela vem da mesma extração.
• Mantenha o hedge da fonte ("pode", "parece", "poderia ser devido a") e sua população.
• A própria leitura do wiki é rotulada como do wiki; nunca a escreva como o ato ou conclusão da fonte.

Apenas as linhas que sobreviverem vão para os passos 6 e 7.

6. Propagar para anotações de conceito

Para cada conceito do passo 5:

1. Verifique se concepts/{Nome_Conceito}.md existe.
2. Existe: anexe a descoberta com um backlink [[anotacao_artigo]] em "Descobertas Chave". Atualize related_concepts se novos links surgirem.
3. Não existe: aplique as regras de criação em references/CONCEPT-PROPAGATION.md primeiro.

7. Propagar para anotações de método

Para cada método do passo 5:

1. Verifique se methods/{Nome_Metodo}.md existe.
2. Existe: adicione o artigo em "Artigos que Usam Este Método".
3. Não existe: crie a partir de templates/method.md.

8. Atualizar frontmatter da anotação do artigo

Preencha concepts_touched com as anotações de conceito e método criadas ou atualizadas.

Verificar-após-escrever: cada nome em concepts_touched DEVE resolver para uma anotação existente em concepts/ ou methods/. Após escrever, verifique novamente cada nome base. Se um não resolver, crie o stub ausente agora ou remova o nome. Referências pendentes tornam-se deriva de lint silenciosa.

8b. Selar a anotação fonte

Registre a verificação em source_verification da anotação do artigo (uma linha: chave do gerenciador de referências, data, o que foi verificado contra o quê). Em seguida, sele cada par (anotação, trabalho) que recebeu uma descoberta e cujas linhas passaram em 5c: escreva uma pequena especificação JSON e execute python <kit>/tools/seal.py spec.json --dry-run, depois sem --dry-run (formato e regras em docs/SEALS.md). Um trabalho verificado apenas em relação ao seu resumo não recebe selo. Use datas do relógio do sistema (date +%F), nunca as estime.

9. Encerramento

Três edições, depois o relatório. Use field_titlecase_map de wiki.config.json para encontrar a subseção correta para cada novo conceito ou método; nunca anexe a um bloco genérico datado no final de uma seção.

• index.md: se o índice incorporar visualizações do Obsidian Bases (index_mode: bases na configuração), NÃO mantenha listas por anotação; apenas atualize as contagens de ## Quick Stats selecionadas e a linha relevante de ## Coverage by Field, depois releia as tabelas (um wiki fresco não tem nenhuma das seções: pule isso, nada deriva até que você as adicione). No modo manual, adicione a anotação ao slot alfabético correto. Nunca toque em um índice legado congelado.
• Roteamento de Sub-MOC (veja WIKI_SCHEMA.md, Arquitetura de Sub-MOC): resolva o field + subfield da anotação, compute fields/{field-slug}/MOC_{Title_Case_Underscore(subfield)}.md (kebab-case para Title_Case, determinístico, nenhum mapa necessário). Se não existir, crie a partir de templates/submoc.md e adicione uma linha ao índice de Sub-MOCs do MOC de campo. Adicione a anotação na seção correta do sub-MOC (Notas de Conceito, Notas de Método, Artigos, Livros)

... [truncado para tradução]