MinorBaek/wiki-ingest

¿Qué hace wiki-ingest?

Implementa el patrón de ingesta LLM-wiki para una base de conocimiento científica. Cada artículo ingerido crea conocimiento rastreable y acumulativo, no solo una nota aislada.

Antes de la primera ingesta, lee docs/GOTCHAS.md en el kit (problemas operativos para ingesta, síntesis y lint).

Modos

• predeterminado (ingesta): /wiki-ingest <artículo> crea o actualiza la nota del artículo y propaga a conceptos y métodos (Flujo de Trabajo Predeterminado a continuación).
• modo verificar: /wiki-ingest verify:<NotaDelArtículo> vuelve a verificar una nota existente contra su texto completo e informa diferencias sin regenerar ni sobrescribir nada (consulta references/VERIFY-DIFF-MODE.md). Solo lectura a menos que el usuario confirme cada edición.

Rol y Límites

Hace: crear o actualizar notas de artículos, propagar a notas de conceptos y métodos, actualizar el índice y el registro, informar cada cambio.

NO hace: inventar citas, crear notas de concepto para conceptos de un solo uso, o escribir en una base de datos. Todas las escrituras pasan por las herramientas de archivo del anfitrión (Leer/Escribir/Editar).

Dónde viven las cosas

Las rutas provienen de wiki.config.json (raíz del vault, raíz de la wiki, nombres de carpeta, idioma, umbrales). Valores predeterminados:

<vault_root>/
  <wiki_root>/            # predeterminado: wiki/
    papers/  concepts/  methods/  books/  fields/  debates/
    WIKI_SCHEMA.md        # contratos de frontmatter, nomenclatura, taxonomía, protocolo de ingesta
    index.md  log.md
  templates/              # paper.md, concept.md, method.md, book.md, chapter.md, submoc.md, synthesis.md

<kit> a continuación se refiere al checkout de science-wiki-kit que contiene tools/ (seal.py, pmc_tables.py). Su ruta es la clave kit_dir de wiki.config.json, escrita por el instalador; si falta, está dos carpetas por encima del directorio de esta habilidad cuando la habilidad está vinculada desde el checkout.

Lee siempre WIKI_SCHEMA.md antes de empezar. Define los contratos de frontmatter, las reglas de nomenclatura y la taxonomía de campo de esta wiki.

Habilidades relacionadas

• wiki-lint: comparte wiki.config.json (el mapa de campo de kebab-case a Title Case utilizado en las actualizaciones del índice). Ejecútalo después de cada ingesta para verificar que no se haya introducido ninguna desviación.
• wiki-ingest-book: habilidad complementaria para libros y capítulos. Se aplican las mismas reglas de estado y enrutamiento del índice.
• wiki-synthesize: consume las notas que produce esta habilidad.

Decisión de estado inicial (aplicada a cada nota nueva)

Establece status deliberadamente. No dejes el valor predeterminado de la plantilla. N a continuación es min_distinct_sources_for_final en la configuración (predeterminado 2).

Tipo de nota	Condición	status inicial
Artículo	Resumen + al menos 2 hallazgos con fuente extraídos	read
Artículo	Solo metadatos de DOI/título, sin texto completo	stub + > [!warning] Stub: ingesta pendiente. callout
Concepto	Al menos 2 hallazgos con fuente de N o más obras fuente distintas	final
Concepto	Al menos 2 hallazgos con fuente, todos de una obra fuente única	draft (síntesis de fuente única)
Concepto	Definición + 1 hallazgo con fuente	draft
Concepto	Solo definición, sin Hallazgos Clave	stub + > [!warning] Stub: aún no hay hallazgos con fuente. callout
Método	Definición + N o más obras fuente distintas en "Papers Using This Method"	final
Método	Definición y solo 1 obra fuente	draft (fuente única)
Método	Definición pero sin citas de fuente	draft
Método	Solo esqueleto	stub

La promoción a final requiere N obras fuente DISTINTAS. "Distintas" cuenta artículos o libros independientes: una nota padre de libro y sus propias notas de capítulo (Autor_2025 + Autor_2025_Ch01 + Autor_2025_Ch02) se colapsan en una obra, al igual que varios capítulos del mismo libro. Una sola fuente rica (revisión sistemática, capítulo de libro de texto) puede crear un concepto y generar varios hallazgos, pero la nota permanece en draft hasta que una segunda fuente independiente lo corrobore. Al agregar un hallazgo a una nota draft, cuenta las obras distintas después de la edición, promueve solo si el conteo alcanza N, y registra la promoción en el informe de ingesta. Las notas draft de fuente única llevan una línea breve "síntesis de fuente única, corroborar cuando se ingiera una 2ª fuente" en el cuerpo.

Flujo de Trabajo Predeterminado

1. Leer esquema

Lee WIKI_SCHEMA.md.

2. Resolver la fuente del artículo

Intenta en orden, utilizando lo que tu entorno proporcione:

• Gestor de referencias (Zotero MCP es el adaptador compatible): buscar, luego metadatos, luego texto completo. Secuencia y problemas de búsqueda en references/INGEST-WORKFLOW.md.
• Tablas XML del editor (acceso abierto en PMC): si el DOI tiene un PMCID, las tablas se pueden extraer celda por celda de Europe PMC JATS, independientemente de la capa de texto del PDF: python <kit>/tools/pmc_tables.py <DOI> --out _temp/<stem>_pmc.md --body (código de salida 2 significa que no hay PMCID). Verifica los números de tabla contra el JATS antes de abrir la imagen de la página; en caso de discrepancia JATS-versus-PDF, gana el PDF impreso y se anota la discrepancia. Sin PMCID: usa el PDF.
• PubMed MCP (artículo no en el gestor de referencias): buscar por palabras clave, luego recuperar por PMID (un DOI puede devolver un full_text vacío). Almacena el PMID en el campo notes: de la nota del artículo. Usar solo para artículos biomédicos y después de que el usuario confirme que no está en su biblioteca.
• Solo DOI: anótalo; no fabriques metadatos.
• Artículo web (HTML/URL de acceso abierto): convertirlo primero a markdown limpio con una herramienta web-to-markdown (por ejemplo, la habilidad defuddle), luego tratar el resultado como resumen y cuerpo. Usa la URL como fuente de cita cuando no haya DOI.
• Manual: el usuario pega el resumen o texto. Extrae los metadatos y marca lo que es desconocido.

Dónde vive el PDF importa: la nota nunca debe citar una carpeta de trabajo (Downloads/, un directorio temporal) que se limpiará. Organiza el PDF en la ubicación de la biblioteca que usa tu grupo antes de escribir la nota, y regístralo en source_verification. Si el artículo no está en la biblioteca, o la colección correcta no está clara, pregunta al usuario antes de mover nada.

3. Determinar el nombre del archivo de la nota del artículo

Formato: PrimerAutor_Año_PalabraClave.md

• PrimerAutor = apellido del primer autor (solo ASCII, sin acentos, sin espacios)
• Año = 4 dígitos
• PalabraClave = descriptor de 1 a 3 palabras (CamelCase o guiones bajos, sin espacios)
• Ejemplo: Smith_2023_Eccentric_Training.md

Verificación de duplicados e identidad (ejecutar antes de cualquier escritura; protege contra la pérdida silenciosa de datos):

1. Confirma la existencia con una búsqueda de contenido por el nombre base, o test -f "<wiki_root>/papers/{nombre}.md". NO confíes en un solo glob que devuelva "no se encontraron archivos": las herramientas de glob de archivos han devuelto falsos negativos para notas que existían, y una Write ciega después sobrescribiría una nota completamente propagada. Si Write da error con "File has not been read yet", esa es prueba de que la nota existe: léela y actualiza en el lugar, nunca la reescribas desde cero.
2. Si la nota existente tiene status: stub, no asumas que es el mismo artículo. Los stubs creados a partir del contexto de cita de otro artículo llevan metadatos provisionales y a veces son un artículo diferente (año incorrecto, artículo versus capítulo de libro, dos artículos hermanos confundidos). Resuelve la fuente real primero y compara autores, año y revista tanto con el stub como con la lista de referencias de la nota citante. Si es un artículo diferente, ingiérelo como una NOTA nueva y conserva o mejora el stub.
3. Si se confirma el mismo artículo, actualiza en el lugar; nunca crees un duplicado. El nombre del archivo puede cambiar legítimamente a una palabra clave más descriptiva una vez que tengas el texto completo. Si es así, vuelve a vincular cada [[NombreAntiguo]] y elimina el stub huérfano, luego vuelve a ejecutar wiki-lint para confirmar que no queden enlaces rotos.
4. Guardia de identidad de citekey. Dos notas para el mismo artículo pueden tener nombres de archivo diferentes, por lo que una prueba limpia del nombre base no demuestra nada sobre la identidad. Una vez que el gestor de referencias haya resuelto el elemento, busca en papers/ el citekey exacto que estás a punto de escribir (grep -l '^citekey: "\?{citekey}"\?$' papers/*.md). Un acierto en un nombre de archivo diferente significa que el artículo ya está ingerido: actualiza esa nota en su lugar. Coincidencia exacta de cadena, por lo que no hay falsos positivos.

4. Crear o actualizar la nota del artículo

Escribe <wiki_root>/papers/{nombre}.md a partir de templates/paper.md. Llena cada campo de frontmatter con los metadatos resueltos. Establece last_verified en la fecha de hoy (la ingesta es un evento de verificación). Asigna research_lines a partir de los slugs de taxonomía en WIKI_SCHEMA.md.

5. Extraer y evaluar

Una pasada sobre el resumen, resultados y discusión, haciendo todo esto a la vez:

• Identificar de 3 a 8 conceptos del dominio (constructos empíricos, variables) y de 1 a 4 métodos principales. Heurísticas en references/INGEST-WORKFLOW.md.
• Clasificar evidence_level: el diseño del estudio, del vocabulario controlado en WIKI_SCHEMA.md (SR-MA, RCT, cohort, ...). Este es el eje de diseño que la capa de síntesis viva pondera. El eje de calidad de medición permanece en línea en cada hallazgo cuando sea relevante ((MRI), (estimación antropométrica)), nunca en el frontmatter.
• Enrutamiento de línea de investigación: empareja el artículo con las líneas de investigación en WIKI_SCHEMA.md. Si el contenido relevante no tiene una línea coincidente, agrega una al esquema antes de propagar (añade un par slug + etiqueta; nunca renombres ni elimines líneas existentes). Si es dudoso, usa la línea más cercana y márcalo en el informe.
• Enrutamiento de concepto versus método: los hallazgos empíricos van a concepts/; las herramientas estadísticas, diseños de estudio y protocolos de medición van a methods/. Decide aquí.
• Atajo puramente metodológico: si el artículo no hace afirmaciones empíricas, omite el paso 6 y ve al paso 7.

5b. Tabla de evidencia, antes de cualquier propagación

Para cada hallazgo que llegará a una nota en concepts/ o methods/ (incluyendo una afirmación bajo "Papers Using This Method"), escribe una fila en un archivo temporal (nunca en la wiki):

| Nota objetivo | Hallazgo, tal como se escribirá | Cita textual de la fuente | Página (PDF / impreso) | Sección, tabla o figura |

• La fuente es el PDF (o el JATS para celdas de tabla). Solo resumen o sin PDF: marca el hallazgo solo resumen en su texto y díselo en el informe.
• Cada específico necesita su cita: cada figura, población, dispositivo, mecanismo, entidad nombrada y verbo de fuerza. Divide el hallazgo, o usa varias citas, hasta que todo esté cubierto.
• Lee todo el párrafo o fila de la tabla alrededor del acierto, no solo el número coincidente.
• Tablas, figuras, signos, IC y ±: renderiza la página y mírala. La extracción de texto es una hipótesis, la imagen es la prueba. Algunos PDF pierden el signo menos en la capa de texto (-5.2% se extrae como 25.2%), produciendo un número falso plausible.
• La ausencia necesita una búsqueda positiva, tanto en texto con diseño como sin diseño y con variantes ortográficas, antes de escribir algo como "el artículo no...".

5c. Verificar la tabla antes de escribir

Lee cada fila contra su cita antes de tocar cualquier nota. Si un subagente extrajo el artículo, vuelve a leer cada fila en el PDF, no solo las filas con una figura o signo. Clases de defectos a juzgar: inferencia más allá de la fuente, error de atribución, número incorrecto, matiz perdido, superlativo no respaldado, entidad incorrecta, detalle inventado, omisión.

• Una fila cuya cita no la respalda debe reformularse a lo que dice la cita, o eliminarse. La nota fuente no es evidencia: proviene de la misma extracción.
• Mantén el matiz de la fuente ("puede", "parece", "podría deberse a") y su población.
• La propia lectura de la wiki se etiqueta como de la wiki; nunca se escribe como el acto o conclusión de la fuente.

Solo las filas que sobreviven van a los pasos 6 y 7.

6. Propagar a notas de concepto

Para cada concepto del paso 5:

1. Verifica si concepts/{Nombre_Concepto}.md existe.
2. Existe: añade el hallazgo con un enlace de retorno [[nota_del_artículo]] bajo "Key Findings". Actualiza related_concepts si surgen nuevos enlaces.
3. No existe: aplica primero las reglas de creación en references/CONCEPT-PROPAGATION.md.

7. Propagar a notas de método

Para cada método del paso 5:

1. Verifica si methods/{Nombre_Método}.md existe.
2. Existe: añade el artículo bajo "Papers Using This Method".
3. No existe: crea a partir de templates/method.md.

8. Actualizar frontmatter de la nota del artículo

Llena concepts_touched con las notas de concepto y método creadas o actualizadas.

Verificar después de escribir: cada nombre en concepts_touched DEBE resolverse a una nota existente en concepts/ o methods/. Después de escribir, vuelve a verificar cada nombre base. Si uno no se resuelve, crea el stub faltante ahora o elimina el nombre. Las referencias colgantes se convierten en desviación silenciosa del lint.

8b. Sellar la nota fuente

Registra la verificación en el campo source_verification de la nota del artículo (una línea: clave del gestor de referencias, fecha, qué se verificó contra qué). Luego sella cada par (nota, obra) que recibió un hallazgo y cuyas filas pasaron 5c: escribe una pequeña especificación JSON y ejecuta python <kit>/tools/seal.py spec.json --dry-run, luego sin --dry-run (formato y reglas en docs/SEALS.md). Una obra verificada solo contra su resumen no recibe sello. Toma las fechas del reloj del sistema (date +%F), nunca las estimes.

9. Cierre

Tres ediciones, luego el informe. Usa field_titlecase_map de wiki.config.json para encontrar la subsección correcta para cada nuevo concepto o método; nunca añadas a un bloque comodín con fecha al final de una sección.

• index.md: si el índice incrusta vistas de Obsidian Bases (index_mode: bases en la configuración), NO mantengas listas por nota; solo actualiza los conteos curados de ## Quick Stats y la fila relevante de ## Coverage by Field, luego vuelve a leer las tablas (una wiki fresca no tiene ninguna sección: omite esto, nada se desvía hasta que las agregues). En modo manual, añade la nota al espacio alfabético correcto. Nunca toques un índice heredado congelado.
• Enrutamiento de Sub-MOC (consulta WIKI_SCHEMA.md, Architecture Sub-MOC): resuelve el field + subfield de la nota, calcula fields/{field-slug}/MOC_{Title_Case_Underscore(subfield)}.md (kebab-case a Title_Case, determinista, no se necesita mapa). Si no existe, créalo a partir de templates/submoc.md y añade una fila al índice Sub-MOCs del MOC de campo. Añade la nota bajo la sección correcta del sub-MOC (Notas de Concepto, Notas de Método, Artículos, Libros).
• log.md: añade una entrada en log.md con la fecha, status y operación (ingesta:create | ingesta:update | verify:pass | verify:diff). Formato: - {date} | {filename} | {status} | {operation} | {conceptos tocados separados por comas}.

10. Generar informe para el usuario

Usa este formato (tabla en markdown, nunca desordenes el wikitext):

---

Informe de ingesta: {filename}

Aspecto	Resumen
Nota del artículo	{filename} → {status}
Conceptos creados	{n} ({lista}) o ninguno
Conceptos actualizados	{n} ({lista}) o ninguno
Métodos creados	{n} ({lista}) o ninguno
Métodos actualizados	{n} ({lista}) o ninguno
Sellos aplicados	{n} ({lista}) o ninguno
Advertencias	{n}

Notas:

• {hallazgos extraídos solo del resumen, si los hay}
• {discrepancias JATS-vs-PDF, si las hay}
• {desviaciones o decisiones dudosas}

Próximos pasos sugeridos:

• Agregar el artículo a tu Zotero si aún no está
• Ejecutar wiki-lint para verificar la consistencia de la wiki
• {cualquier otra acción}