From 70d3ab883ad7cb22826a2845daee46c90fa5eb78 Mon Sep 17 00:00:00 2001 From: complexluise Date: Tue, 30 Jun 2026 21:19:34 -0500 Subject: [PATCH 1/4] chore(gitignore): ignorar workspaces locales de sesiones (ied-presentacion, pensamiento-complejo-grafo) --- .gitignore | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.gitignore b/.gitignore index 836353b..e456e6f 100644 --- a/.gitignore +++ b/.gitignore @@ -215,3 +215,7 @@ dist vite.config.js.timestamp-* vite.config.ts.timestamp-* .vite/ + +# LOCAL-ONLY (no commitear): artefactos de sesión, no se versionan (decisión PO 2026-06-22) +examples/ied-presentacion/ +examples/pensamiento-complejo-grafo/ From aeddf1fd9f5475fbbaa1ce0dd4002ce8ff69be7a Mon Sep 17 00:00:00 2001 From: complexluise Date: Thu, 2 Jul 2026 11:29:21 -0500 Subject: [PATCH 2/4] docs(notas): publicar notas 29 (jubilar debate a Discussions), 30 (paper JOSS) y 31 (feedback bib2graph) --- .../29-jubilar-notas-debate-a-discussions.md | 279 +++++++++ docs/Notas/30-paper-joss-doi-citable.md | 88 +++ docs/Notas/31-feedback_bib2graph.md | 543 ++++++++++++++++++ 3 files changed, 910 insertions(+) create mode 100644 docs/Notas/29-jubilar-notas-debate-a-discussions.md create mode 100644 docs/Notas/30-paper-joss-doi-citable.md create mode 100644 docs/Notas/31-feedback_bib2graph.md diff --git a/docs/Notas/29-jubilar-notas-debate-a-discussions.md b/docs/Notas/29-jubilar-notas-debate-a-discussions.md new file mode 100644 index 0000000..7d9326c --- /dev/null +++ b/docs/Notas/29-jubilar-notas-debate-a-discussions.md @@ -0,0 +1,279 @@ +# 29 — Jubilar `docs/Notas/`: debate a Discussions, histórico a Wiki, contrato queda en el repo + +> **Estado:** propuesta, pendiente de revisión del PO (2026-07-01). +> **Naturaleza:** Nota de propuesta. **No es ADR todavía** — el ADR baja después de +> revisarla. Esta nota documenta el cambio **antes** de ejecutarse porque rompe una +> convención del repo (la existencia misma de `docs/Notas/` como superficie viva). +> +> ⚠️ **BREAKING CHANGE.** Aunque no toca código, cambia: +> - la convención de género (Notas-archivo jubilan, debate va a Discussions); +> - el estado de ADRs vigentes (0032/0033 → Rechazadas; 0035 → Aceptada en el índice); +> - la ruta de `docs/metodologia.md` (sale de `docs/Notas/`, vive en `docs/`); +> - la existencia de 6 archivos (`NO-HACER-COMMIT-*` se borran); +> - la creación de 4 Discussions y 3 categorías de Wiki que no existían. +> +> Por todo esto se documenta como breaking en el commit (`BREAKING CHANGE:` en el footer +> del commit o `feat!:`), independientemente de que no toque código. + +## 1. El problema + +`docs/Notas/` acumula **31 Notas + 6 borradores + 3 documentos de glosario/método**. +Para un investigador o desarrollador nuevo en el repo: + +- No sabe **cuál es contrato, cuál es debate, cuál es histórico, cuál es borrador**. +- Están mezcladas con la doc viva (`docs/API.md`, `docs/ARCHITECTURE.md`, `docs/PRD.md`). +- Algunas son densas y narrativas (`Nota 18 — flujo canónico de biblioteca`, + `Nota 28 — marco de software`), pensadas para que el PO debata consigo mismo, no para + que un dev nuevo las lea. +- Las más viejas (07, 08, 10, 12, 16) son de la era GUI local — ya **supersedidas por + ADR 0040 (retiro de la GUI)** — pero siguen vivas en disco. + +Sumado a eso: + +- Hay **4 ADRs en estado Propuesta** (0032, 0033, 0034) que perdieron su consumidor con + el retiro de la GUI local (0040). Zombies. +- Hay **2 ADRs perdidos del filesystem** (0042, 0044) que existen en git pero no están + en el árbol actual. Drift. +- Hay **5 Notas que encierran debates vivos** (22 frontera, 25 multi-proveedor, + 27 recibo de demo, 28 posicionamiento, 23 retroalimentación agente) que merecen un + hogar mejor que `docs/Notas/`. + +## 2. La dirección + +Reencuadre de la partición de géneros (que hoy está implícita en la skill `flujo` y se +vuelve explícita acá): + +| Género | Dónde vive hoy | Dónde vive mañana | Por qué | +|---|---|---|---| +| Contrato del producto (qué hace) | `docs/API.md`, `docs/ARCHITECTURE.md`, `docs/PRD.md` | igual | Se mueve en lockstep con el código; PR + CI obligatorio | +| Decisión (por qué) | `docs/decisiones/0001–0043` | igual | Inmutable, citado desde código y otros docs | +| Plan / roadmap | `docs/ROADMAP/` | igual | Cambia con cada hito | +| Reglas del repo | `CONTRIBUTING.md`, `AGENTS.md` | igual | Cómo se trabaja; cómo contribuyen humanos y agentes | +| **Debate vivo (tensión, propuesta)** | **`docs/Notas/` (mezclado)** | **GitHub Discussions (con encabezado estándar)** | Las Discussions viven en el lugar donde realmente se debate; pueden cerrarse sin dejar basura en el repo | +| **Mapa / onboarding / glosario / historia** | **`docs/Notas/` (mezclado)** | **GitHub Wiki** | Estable, narrativo, no requiere PR | +| **Historial / rastro muerto** | **`docs/Notas/` (mezclado)** | **`docs/_archivo/` con `.no-commit`** (no versionado) | Cosas que el PO ya no quiere vivas pero no quiere borrar | +| Borradores del PO | `docs/Notas/NO-HACER-COMMIT-*` | **borrar** | No son notas; son work-in-progress | + +**La regla "no se crean Notas-archivo nuevas" se mantiene — pero la práctica de crearlas +se jubila.** Las que existen, se mueven. + +## 3. Lo que cambia + +### 3.1. Estructura de carpetas del repo + +``` +docs/ +├── PRD.md (sin cambios) +├── ARCHITECTURE.md (sin cambios) +├── API.md (sin cambios) +├── ROADMAP/ (sin cambios) +├── decisiones/ (sin cambios en estructura) +│ ├── README.md (3 filas actualizadas: 0032/0033 Rechazadas, 0035 Aceptada) +│ ├── 0001–0043.md (0032 y 0033 marcados como Rechazada — Supersedida por 0040) +│ └── 0034-etiquetado-tabla-tags-lateral.md (nota de estado agregada: "referencia técnica reusable") +├── metodologia.md (movido desde docs/Notas/, vive en docs/ como autoridad de método) +├── Notas/ (jubilada — ver §3.2) +└── _archivo/ (NUEVO — ver §3.2) + ├── .no-commit (sentinel: explica que esto no se versiona) + └── notas/ (todo el contenido de docs/Notas/ movido acá, sin selección) +``` + +### 3.2. Destino de `docs/Notas/` — todo se mueve, la selección se hace después + +`docs/Notas/` se mueve **completo** a `docs/_archivo/notas/` con `mv` (preservando historia +via git). Esto incluye las 31 notas, los 6 borradores `NO-HACER-COMMIT-*`, los subdirectorios +`02-exploracion/` y `03-referencia/`, y los 3 docs sueltos (`critica-base.md`, +`metodología.md`, `referentes.md`). + +**No se hace selección manual acá.** El criterio rector es: si el PO (o quien revise) +quiere resurrectar algo, está en `_archivo/`. La selección fina de qué sube al Wiki o a +Discussions se hace en una segunda pasada, con tiempo, no en bloque. + +Después del movimiento: + +- `docs/metodologia.md` se **extrae de `_archivo/notas/`** y se mueve a `docs/metodologia.md` + como documento vivo (autoridad de método). Es la única Nota que vive en el repo porque + su rol es ser referencia de método, no contrato ni debate. +- Las **reglas duras** de la `Nota 01 — lecciones de v0` se **extraen** a `CONTRIBUTING.md` + y `AGENTS.md` (ya están citadas en ambos; la nota se borra de `_archivo/notas/` si su + contenido ya vive en otra parte). +- Los **6 borradores `NO-HACER-COMMIT-*`** se **borran** de `_archivo/notas/`. No eran + notas, eran work-in-progress del PO. + +### 3.3. ADRs zombies + +Los ADRs 0032, 0033, 0034 son Propuesta de la era GUI y perdieron su consumidor con el +retiro de la GUI local (0040): + +- **0032 (`capa-servicios-duena-del-flujo`)** → estado cambia a **"Rechazada — Supersedida + por 0040"**. Encabezado: 1 línea. Cuerpo: 1 bloque de Enmienda fechado (3 líneas) + explicando que la GUI murió y `service/` se conserva parcialmente. +- **0033 (`producto-library-centric-grafo-proyeccion`)** → mismo tratamiento. La idea + "BIBFRAME fuera" sobrevive como decisión implícita; se anota en `docs/metodologia.md` + si el PO lo decide (no requiere ADR propio). +- **0034 (`etiquetado-tabla-tags-lateral`)** → se queda como **Propuesta-referencia + técnica**. Una línea en el bloque de estado: "Referencia técnica para tablas laterales + (`referenced_but_not_fetched`, `loop_state_log`); no se promueve porque el consumidor + (GUI) murió. BUG-2 (extensibilidad del schema) queda como decisión abierta del PO." + +El `docs/decisiones/README.md` se actualiza con 3 líneas: 0032 → Rechazada, 0033 → +Rechazada, 0035 → Aceptada (drift menor del índice). + +### 3.4. ADRs perdidos del filesystem (0042, 0044) + +- **0042 (Semantic Scholar como 2º motor)** — existe en commit `a27aa09`, no está en el + árbol actual, README sí lo lista. **Decisión propuesta: dejarlo así.** El código + existe, los issues referencian el número. Si alguien reporta fricción, se recupera en + una PR de hygiene aparte. **No incluir en este cambio** (sería inflar el breaking + change). +- **0044 (precedencia de inclusión manual en curate)** — existe en commit `3417c68`, + mismo caso. Misma decisión: dejar así. + +### 3.5. Discussions nuevas — el nuevo hogar del debate vivo + +Se abren **4 Discussions** con un encabezado estándar que las haga útiles como referencia +futura: + +```markdown +## Pregunta + +[Una pregunta concreta, no un resumen de la Nota] + +## Contexto + +Esta discusión nace de `docs/Notas/NN-titulo.md` (archivado en `docs/_archivo/notas/`). +[5–10 líneas de la tensión] + +## Si esta discusión converge, qué cambia + +- ADR nuevo (¿#XXXX?) con la decisión formal, O +- Cerrar como "no resuelve" sin ADR + +## Estado + +- [ ] Discusión abierta +``` + +Las 4 Discussions que se abren: + +1. **"Frontera de producto: ¿qué entra y qué no en bib2graph?"** — origen `Nota 22`. + Tensión: bib2graph como herramienta vs como suite. Cierra el hueco que ningún ADR + fija con esa claridad (0022 cubre "sin IA"; 0008 cubre forrajeo; "no interpreta, no + gestiona investigación" no está). +2. **"Multi-proveedor: cómo priorizar el 2º motor y la capa Sur-global"** — origen + `Nota 25`. Tensión: S2 vs DOAJ vs SciELO vs CrossRef; el probe empírico ya hizo la + criba pero el orden de implementación no está. +3. **"Extensión de `maturity`: `crossed_red` / `assumed_judgment` / `orphans`"** — + origen `Nota 27`. Tensión: el bloque `maturity` actual (`curated`, `scope`, + `saturated`, `empty_networks`) ya está documentado en `docs/API.md`;该不该 extenderlo + con recibos de juicio humano. +4. **"Posicionamiento de bib2graph: ¿qué tradiciones reivindicamos?"** — origen + `Nota 28`. Tensión: 5 pilares (FCIS, Hexagonal, build hermético, Unix-for-agents, + tools-for-thought determinista); §2-bis de calibración honesta (build hermético = + solo dirección por contenido, no cache-hit; hash plano no Merkle; CLI fail-open + advisory). + +### 3.6. Wiki — el nuevo hogar de lo narrativo + +Se crean **3 categorías** en el Wiki del repo (la Wiki está habilitada): + +- **Wiki / Historia** — `Nota 04` (dirección IA-in-the-loop), `Nota 06` (red-team v0.2), + `Nota 07/08/10/12/16` (era GUI), `Nota 13/14/15/17/19` (QA/sesión). Son rastros del + proceso. +- **Wiki / Papers en progreso** — `Nota 20_ciclo_investigacion_hallazgos_teoricos`, + `Nota 24_referente-snowballing-comparacion`. Son insumos del paper que el PO está + escribiendo. +- **Wiki / QA / footguns** — tabla consolidada de bugs footgun-invisible encontrados en + sesiones (extraídos de las Notas de QA). + +## 4. Por qué es BREAKING (aunque sea docs) + +- **Cambia la convención de género.** Cualquier nota o debate futuro que se hubiera + puesto en `docs/Notas/` ahora va a Discussions. Es un cambio de flujo de trabajo, no + solo de archivos. +- **Borra 6 archivos** (`NO-HACER-COMMIT-*`). Aunque sean borradores, son archivos que + existían en disco. +- **Mueve archivos a una carpeta no versionada** (`docs/_archivo/`). Un dev que espera + encontrar todo en git se va a sorprender. +- **Cambia el estado de ADRs vigentes** (0032, 0033 → Rechazadas; 0035 → Aceptada en el + índice). Quien referencie estos ADRs por nombre debe saber que ya no son propuestas + activas. +- **Abre 4 Discussions y crea 3 categorías de Wiki** que no existían. La fricción para + el PO es administrativa (crear las Discussions manualmente o vía API). + +Por todo esto **debe documentarse como breaking en el commit** (`BREAKING CHANGE:` en +el footer del commit o `feat!:`), independientemente de que no toque código. + +## 5. Lo que NO se hace (explícito) + +- **No se borra `docs/Notas/`** — se mueve a `_archivo/`. +- **No se borran los ADRs zombies** — se marcan como Rechazados. +- **No se crea** ADR 0045 (frontera) ni 0046 (posicionamiento). Esas ideas van a + Discussions; si convergen, recién bajan a ADR. +- **No se recuperan** los ADRs 0042 y 0044 perdidos del filesystem. Si alguien reporta + fricción, se hace en una PR aparte. +- **No se toca código.** Es 100% docs. +- **No se hace selección fina de qué sube a Wiki** en este pase. La selección se hace + en una segunda iteración, con tiempo. + +## 6. Plan de ejecución (cuando el PO apruebe esta Nota) + +5 PRs + apertura/cierre de Discussions, todos `docs/chore`, ninguno toca código: + +| # | PR | Archivos | Tipo | +|---|---|---|---| +| 1 | `chore(docs)!: jubilar docs/Notas/ → docs/_archivo/notas/` | ~37 movidos + 6 borrados + 1 sentinel | `chore!` (breaking) | +| 2 | `docs(adr)!: rechazar 0032/0033 (Supersedidas por 0040) + fix README 0035 + nota en 0034` | 4 archivos | `docs!` (breaking en docs vivos) | +| 3 | `docs(meta): tabla de géneros de documentación en AGENTS.md` | 1 archivo | `docs` | +| 4 | `docs(meta): extracto de reglas duras de la Nota 01 a CONTRIBUTING.md` | 1 archivo | `docs` | +| 5 | `docs!: extraer docs/metodologia.md desde _archivo/notas/` a `docs/metodologia.md` (autoridad de método)` | 1 archivo movido + refs actualizadas | `docs!` (cambio de path) | + +Y fuera de PRs: + +- 4 Discussions abiertas (vía `gh` o web UI). +- 3 categorías de Wiki creadas. + +**Orden sugerido:** PR 1 (mover Notas) → PR 2 (rechazar zombies) → PR 5 (`metodologia`) +→ PR 3 (AGENTS) → PR 4 (CONTRIBUTING). Cada PR es independiente en archivos, no hay +conflictos entre ellos. + +## 7. Riesgos y rollback + +- **Riesgo 1:** un dev nuevo busca una Nota específica y no la encuentra en + `docs/Notas/`. **Mitigación:** el README y `AGENTS.md` explican la nueva partición; el + `_archivo/` está local (no requiere red) para quien quiera consultar. +- **Riesgo 2:** los ADRs rechazados (0032/0033) se referencian desde código o docs como + si siguieran vigentes. **Mitigación:** buscar refs antes de cerrar el PR; actualizar + las refs para que apunten al ADR que sí está vigente. +- **Riesgo 3:** la Wiki está habilitada pero las categorías requieren crear páginas + manualmente. **Mitigación:** si crear las 3 categorías resulta engorroso, basta con + crear las páginas vacías con un índice que apunte a las Discussions. +- **Rollback:** todos los cambios son revertibles con `git revert`. `_archivo/` es local + pero el contenido sigue en git hasta el merge. + +## 8. Preguntas abiertas para el PO + +1. Las 4 Discussions se abren **antes** del movimiento de Notas (para que las Notas + referencien Discussions vivas) o **después** (para que las Discussions referencien + las Notas archivadas)? — **Decidido:** mantener 2 Discussions separadas (Frontera y + Posicionamiento son debates distintos, no se fusionan). +2. ¿Las categorías de Wiki se crean como páginas vacías con índice, o se sube el + contenido de las Notas relevantes directamente? — **Decidido:** Wiki habilitada, se + crean las 3 categorías. +3. La extracción de la `Nota 01` a `CONTRIBUTING.md` y `AGENTS.md` — ¿se hace como + parte de este breaking (PR 4) o se difiere a una PR aparte (menos superficie de + cambio)? — **Pendiente.** +4. ¿Se mantiene el número `29` para esta Nota (siguiente correlativo) o se usa otra + convención dado que la Nota se archiva a sí misma? — **Decidido:** `29`, siguiente + correlativo. Es la última Nota que se mueve. + +## 9. Meta + +Esta es la **última Nota-archivo que se escribe en `docs/Notas/`**. Después de aprobada +y ejecutada, la carpeta se mueve completa a `docs/_archivo/notas/` y la convención +cambia para siempre: cualquier debate futuro va a GitHub Discussions primero; si +converge en decisión firme, baja a ADR; si no, queda como Discussion cerrada. La +práctica de crear Notas-archivo se jubila junto con la regla que la prohíbe. + +La Nota en sí se archiva en `docs/_archivo/notas/29-…md` después de ejecutarse — meta: +una Nota que se archiva a sí misma. \ No newline at end of file diff --git a/docs/Notas/30-paper-joss-doi-citable.md b/docs/Notas/30-paper-joss-doi-citable.md new file mode 100644 index 0000000..fcd4c7f --- /dev/null +++ b/docs/Notas/30-paper-joss-doi-citable.md @@ -0,0 +1,88 @@ +# 30 — Paper citable con DOI (JOSS) + soporte first-class en español + +> **Género:** nota de dirección (nota primero; no es ADR ni doc canónico). +> **Origen:** charla PO ↔ agente: "quiero hacer un paper de bib2graph, con DOI, que se pueda +> citar en investigación" → ¿el paper debe ir en inglés? → si sí, ¿cómo dar soporte first-class +> a hispanohablantes sin sacrificar eso? +> **Para qué:** fijar el camino (JOSS + Zenodo) y dejar registrado, sin ejecutar todavía, qué le +> falta al repo para cumplir el checklist de revisión de JOSS. +> **Relacionadas:** `25-multiproveedor-requerimientos.md` (misión hispana), `28-marco-software-donde-nos-paramos.md` +> (insumo natural para el "Statement of Need" del paper), `docs-espanol-neutro-tuteo` (memoria: +> docs del sitio siempre en español neutro tuteando). + +--- + +## Decisión de rumbo + +- **Vía elegida: JOSS** (Journal of Open Source Software). Gratis, revisión pública en GitHub, + semanas no meses, da DOI vía Crossref al aceptar. Requiere `paper.md` corto (resumen + + statement of need) + `paper.bib`, apoyado en la documentación existente — no un paper largo + desde cero. +- **Idioma:** el `paper.md` de JOSS **debe ir en inglés** (idioma de revisión editorial e + indexación en Crossref). Eso **no** obliga a traducir el sitio: la documentación (mkdocs) sigue + en **español neutro** como hoy — ese es el soporte first-class a hispanohablantes. El paper es + un artefacto aparte y corto que enlaza a esa documentación. +- Único punto de fricción real: los revisores de JOSS instalan y prueban el software siguiendo + las instrucciones del README — conviene que el *quickstart* mínimo tenga versión en inglés (o + README bilingüe) para que puedan seguirlo sin traducir, aunque el resto del sitio quede en + español. + +--- + +## Checklist de JOSS — estado as-built (auditado 2026-07-01) + +| Requisito JOSS | Estado | Evidencia / gap | +|---|---|---| +| Licencia OSI-approved | ✅ | `LICENSE` = GPL-3.0-or-later, declarada en `pyproject.toml` | +| Repositorio público con control de versiones | ✅ | GitHub, 259 commits | +| Tests automatizados | ✅ | 66 archivos `test_*.py`, gate corre `pytest` | +| Instrucciones de instalación | ✅ | README §Instalación | +| Ejemplo de uso | ✅ | README §Quickstart | +| Documentación de API | ✅ | `docs/reference/python-api.md` | +| Guías de comunidad (contribuir/soporte/reportar) | ⚠️ parcial | `CONTRIBUTING.md` cubre setup/commits/tests/releases; falta sección explícita de "cómo pedir soporte" / "cómo reportar un bug" orientada a usuarxs externxs (hoy es más para contribuir código) | +| **Statement of Need** explícito | ⚠️ falta | README tiene "Qué hace" pero no un statement of need al estilo JOSS (a quién sirve, qué problema resuelve, comparación con alternativas). La Nota 28 (§3 "Prior art y huecos") ya tiene el material — falta destilarlo a inglés y forma de paper | +| Autoría nombrada con afiliación/ORCID | ❌ falta | `pyproject.toml` solo dice `"Equipo bib2graph"`; JOSS pide personas reales con afiliación (ORCID opcional pero recomendado) | +| Política de autoría IA | ⚠️ a decidir | `git log` tiene commits co-autorados por "Claude"; JOSS exige autores humanos — hay que decidir cómo se declara el uso de IA (acknowledgment, no autoría) antes de listar autores en el paper | +| `paper.md` + `paper.bib` | ❌ falta | no existen todavía | +| Archivo permanente con DOI (Zenodo / Software Heritage) | ❌ falta | no hay `.zenodo.json` ni integración GitHub↔Zenodo; JOSS exige un archivo depositado que matchee versión/título/autores antes de aceptar | +| `CITATION.cff` | ❌ falta | no existe; no es requisito duro de JOSS pero GitHub lo usa para "Cite this repository" y ayuda a la citabilidad general | +| Alcance ("substantial scholarly effort", no utilidad menor) | ✅ probable | 259 commits, arquitectura documentada en profundidad (Notas 20–29, ADRs); único matiz: el repo tiene ~2 semanas de historia calendario (2026-06-15 → 2026-06-30) — no es un requisito de JOSS pero puede salir en la revisión editorial | + +--- + +## Lo que falta hacer (no ejecutado — solo mapa) + +1. Decidir autoría real para el paper: nombres, afiliación, ORCID de quién corresponda; decidir + cómo declarar la contribución de IA (agradecimiento, no autoría). +2. Escribir sección explícita de soporte/reporte de bugs en `CONTRIBUTING.md` (o README) para + usuarxs, no solo contribuidores de código. +3. Destilar la Nota 28 (§3 prior art, §4 frases-ancla) a un **Statement of Need** en inglés, + corto y defendible. +4. Redactar `paper.md` (summary + statement of need + referencias) y `paper.bib`. +5. Agregar `CITATION.cff`. +6. Conectar el repo a Zenodo (GitHub integration) y archivar el release que se someta a JOSS, + con versión/título/autores idénticos al paper. + +Nota primero — esto es el mapa del checklist, no la ejecución. Próximo paso natural: decidir +autoría (punto 1) antes de tocar nada más, porque condiciona el resto. + +--- + +## Actualización (2026-07-01): esto es de mediano plazo, no ahora + +Dos cambios de rumbo que aplazan todo lo de arriba: + +- **Licencia:** GPL-3.0 no sirve si la idea es que una empresa pueda usar bib2graph sin + obligación de copyleft. Cambiar a **algo tipo Apache-2.0** (o MIT) — sigue siendo open source + (OSI-approved, no rompe el requisito de JOSS), pero permite uso comercial sin las restricciones + de la GPL. Pendiente: auditar si hay dependencias GPL que impidan el cambio de licencia antes + de ejecutarlo. +- **Timing:** el paper (JOSS) y el archivo con DOI **no tienen sentido todavía**. Hoy bib2graph + "abarca varias cosas" — falta que decante a una versión más estable y más **Unix** (que + resuelva bien **un** problema, filo con `frontera-bib2graph-vs-producto`) antes de intentar + publicarlo como paper citable. Publicar ahora sería citar una superficie que todavía se está + recortando. + +**Conclusión:** esta nota queda como mapa de mediano plazo. No es el próximo paso de esta +semana ni del próximo hito — se retoma cuando (a) el alcance esté recortado a algo más Unix y +(b) la licencia ya sea permisiva. diff --git a/docs/Notas/31-feedback_bib2graph.md b/docs/Notas/31-feedback_bib2graph.md new file mode 100644 index 0000000..b4f87dd --- /dev/null +++ b/docs/Notas/31-feedback_bib2graph.md @@ -0,0 +1,543 @@ +# Retroalimentación del uso de bib2graph + +_Informe de feedback sobre una sesión end-to-end de bib2graph v0.11.0 +(instalación → seed → chain → build → informe del estado del arte), con +dos voces diferenciadas: **👤 usuario no técnico** (quien opera) y +**🤖 agente IA** (quien asiste). El reporte secciona el flujo en cuatro +momentos: instalación, forrajeo (seed/chain/build), producción del +artefacto analítico y fricciones transversales del agente._ + +> Esta sesión fue escrita con ánimo constructivo. Los tiempos, errores y +> comandos citados son reales y verificables. La herramienta evoluciona +> rápido; lo que hoy es fricción puede no serlo mañana. El feedback está +> dirigido al mantenedor de bib2graph y a quien use el skill asociado. + +--- + +## 0. Resumen ejecutivo + +| momento | resultado | fricción principal | +|---|---|---| +| Instalación | ✅ limpia, dos comandos | ninguna significativa | +| Forrajeo (seed→chain→build) | ✅ corpus útil (293 papers) | 503 inicial + descubrimiento de la API key | +| Artefacto final (4 markdown + 5 plots) | ✅ entregable de calidad | el primer intento auto-generado fue **rechazado por el usuario**; el valor vino de la lectura real de abstracts por el LLM | +| Fricciones transversales del agente | — | mala lectura inicial, atributos faltantes en graphml, curvas de propagación de env vars | + +**Recomendación de una línea**: bib2graph es una herramienta sólida para +forrajeo bibliográfico agente-native. Su mayor oportunidad de mejora no +está en el core (que funciona), sino en (a) **documentar atributos del +artefacto** (qué hay y qué no en `network.graphml` vs `library.duckdb`), +(b) **hacer explícito el rol del LLM downstream** para análisis de +contenido, y (c) **endurecer el manejo de autenticación de OpenAlex** (api_key). + +--- + +## 1. Instalación + +### 👤 Usuario (no técnico) + +> "Instalé con uv y funcionó. El banner del CLI me llamó la atención: se +> autodefine como 'agente-native'. Eso me hizo pensar que estaba hecha +> para trabajar con un asistente IA, y la verdad es que sí, fue la +> sensación durante toda la sesión." + +**Lo que funcionó**: +- `uv tool install bib2graph` corrió sin fricción. +- `uv tool upgrade bib2graph` llevó de 0.10.0 a 0.11.0 sin + intervención. +- El binario `b2g` quedó disponible globalmente. + +**Lo que costó**: +- Nada material. Una duda menor: el binario adicional `bib2graph` que + quedó instalado junto a `b2g` — no está claro para qué sirve vs. el + canónico. ¿Es un shim? ¿Un entrypoint legacy? + +### 🤖 Agente IA + +> "La instalación fue trivial desde mi lado también. Una nota: confirmé +> el tagline 'CLI agente-native' leyéndolo del `--help`. Ese banner es +> útil: enuncia la promesa del producto y prepara al usuario sobre qué +> esperar." + +**Lo que funcionó**: +- Detección automática de la versión, binario y subcomandos. + +**Fricción observada**: +- **Binarios duplicados sin documentación**: `uv tool install` produjo + dos ejecutables (`b2g` y `bib2graph`). No hubo mensaje explicativo. + Recomiendo: o deprecar `bib2graph` con un mensaje al usarlo, o + documentar la diferencia en `--help`. + +--- + +## 2. Forrajeo: seed, chain, build + +### 2.1 La ecuación + +#### 👤 Usuario + +> "La primera ecuación era buena y ambiciosa: emergenciamás sistemas +> complejos más reduccionismo. Tuvo que ser simplificada porque OpenAlex +> devolvía 503 — algo que atribuimos inicialmente a un outage global pero +> luego descubrimos que era otra cosa." + +#### 🤖 Agente + +> "Cometí un error diagnóstico inicial. El primer 503 me hizo concluir +> 'OpenAlex está caído globalmente'. Era falso. La causa era rate limit +> desde una IP sin auth. Esa mala lectura consumió ~3 turnos de la +> sesión. Lo que me permitió corregir fue la intuición del usuario de +> probar con API key. **Aprendizaje para el skill**: cuando OpenAlex +> devuelve 503 persistente desde un entorno sin auth, **no asumas +> outage**; verificá con `curl` antes de pausar." + +### 2.2 La API key + +#### 👤 Usuario + +> "Yo tenía la key guardada de antes. Se la pasé al agente y dije 'usá +> mi API_KEY'. Pensé que el agente la iba a tomar y listo. No fue tan +> directo: hubo que descubrir que OpenAlex sí la acepta, que bib2graph la +> lee de una variable de entorno específica, y que la env var no se +> propagaba entre los shells del agente. Tardamos varios turnos en +> alinearnos." + +**Fricción reportada**: +- Documentación pública de OpenAlex sugiere que la key no es necesaria; + en la práctica, **sin key, una IP sin auth recibe 503 frecuente**. +- `OPENALEX_API_KEY` no está documentada en `b2g --help`. Tuve que + encontrar la variable buceando en el código de la herramienta. + +#### 🤖 Agente + +> "Cuando el usuario me pasó la key, mi primera respuesta fue 'OpenAlex +> no usa API keys' — **estaba equivocado**. Esa respuesta fue producto de +> lo que dice la doc pública y el `--help` de bib2graph (que no la +> menciona). Tuve que verificar con `curl ?api_key=...` (200 OK) y leer +> el código fuente (`openalex.py:413`) para descubrir: +> +> ```python +> self._api_key = api_key or os.environ.get('OPENALEX_API_KEY') +> ... +> headers['Authorization'] = f'Bearer {self._api_key}' +> ``` +> +> Esto significa dos cosas: +> +> 1. **bib2graph sí soporta api_key**, pero **no lo dice en ninguna +> parte visible al usuario**. Hay un flag `--email` (polite pool) y +> nada más. La variable de entorno `OPENALEX_API_KEY` está +> implementada pero no documentada. +> 2. **El agente tiene que leer el código fuente** para encontrar el +> path correcto. Eso es aceptable para un mantenedor; no lo es para +> un usuario (humano o IA) que solo quiere ejecutar el comando. +> +> **Recomendación concreta**: agregar a `b2g seed --help` una sección: +> +> ``` +> Authentication: +> --email TEXT Email for OpenAlex polite pool (recommended). +> OPENALEX_API_KEY env var improves rate limits (optional but +> recommended for unattended runs). See docs/auth.md. +> ```" + +### 2.3 Propagación de variables de entorno + +#### 🤖 Agente + +> "Otro punto que me costó trabajo: en mi entorno de ejecución, cada +> bash call es un shell nuevo. `set X=Y && comando` en CMD, o +> `export X=Y` en Bash, **no persiste entre invocaciones**. La solución +> que descubrí fue pasar la env var inline: +> +> ```bash +> OPENALEX_API_KEY=... b2g seed ... +> ``` +> +> Esto no es culpa de bib2graph — es del entorno. Pero el usuario +> humano, al ver que 'la env var no se propaga', puede pensar que la +> herramienta está rota. **Recomendación para el skill**: cuando el +> agente explique cómo setear una env var, debe especificar **inline** +> o **cómo exportar persistentemente en el shell del usuario**." + +### 2.4 Chaining costoso + +#### 👤 Usuario + +> "Tuve que esperar casi 5 minutos para el chaining. No fue un problema, +> pero si esto fuera un flujo iterativo de refinamiento sería molesto." + +#### 🤖 Agente + +> "El primer `b2g chain --depth 1` con defaults tardó >5 minutos y +> terminó en timeout (300s). Bajamos `--max-citing` de 50 a 25 y +> `--max-candidates` a 300 — terminó en ~4:43. Sugerencias: +> +> 1. **Documentar tiempos esperados** según tamaño del corpus. Una +> tabla heurística en docs/performance.md ayudaría. +> 2. **Considerar un modo preview más barato**: `--preview` ya existe y +> calcula estimaciones sin fetchear; promoverlo en el `--help` +> ('empezá por acá si tu corpus tiene >200 seeds'). +> 3. **Barra de progreso más informativa**: la actual muestra solo +> 'forward chaining N/M'. Detalle como 'batch X/Y · Z papers +> encontrados hasta ahora' ayudaría a decidir abortar." + +### 2.5 Build y la membresía de cluster + +#### 🤖 Agente + +> "El `b2g build` corrió sin problemas y produjo `clusters.csv` con 6 +> comunidades. Aquí vino la fricción más interesante: la membresía de +> cluster está en `clusters.csv` y en `.corpus_hash`, pero **no como +> atributo de nodo en `network.graphml`**. Esto significa que para +> reproducir el particionado de cluster, hay que correr el algoritmo +> (no es trivial — depende de `python-louvain` y del random_state +> derivado del hash) o leer el CSV. +> +> Mi primera implementación intentó asignar clusters re-corriendo +> Louvain con el mismo `random_state`. **Funcionó**, pero es un punto +> frágil: +> +> 1. Si bib2graph cambia de algoritmo de clustering (de Louvain a otro), +> mi código downstream se rompe silenciosamente. +> 2. Si el usuario cambia `resolution` o `random_state` en build, mi +> código downstream diverge del suyo. +> +> **Recomendación**: persistir el `cluster_id` como atributo de cada +> nodo en `network.graphml` (`N`). Es un +> cambio pequeño en el projector y elimina una clase entera de bugs." + +--- + +## 3. El artefacto final: 4 markdown + 5 plots + +Este es el corazón del reporte, porque es donde el "agente-native" +prometido por el banner se concreta — o se queda corto. + +### 3.1 Primer intento: auto-generación por reglas (rechazado) + +#### 👤 Usuario + +> "El primer informe que me entregó el agente era claramente mediocre. +> Detectaba tags con regex sobre keywords de OpenAlex, asignaba una +> 'idea nuclear' por paper sin leer el abstracto, y rellenaba una PID +> con números arbitrarios. Yo le dije: 'eso no es calidad, vos tenés +> que leer los abstracts'. Era una crítica directa a la confianza del +> agente en sus propias herramientas de reglas." + +#### 🤖 Agente + +> "El primer intento fue un **error estratégico** mío. Tenía Python +> potente (regex sobre texto, conteo de co-ocurrencias, gráficos con +> seaborn) y lo usé para **imitar** el trabajo analítico que solo el +> LLM puede hacer. El output parecía profesional pero era hueco: +> +> - Las 'ideas nucleares' eran inferidas por patrones en el título, no +> por lectura del abstracto. +> - Los 'tags' eran asignados por reglas que matcheaban keywords de +> OpenAlex, no por comprensión del paper. +> - La 'PID' calculaba números pero sin contenido interpretativo. +> +> **Esto fue el momento bisagra de la sesión**. La intervención del +> usuario fue correcta y necesaria. Sin ella, el informe habría sido +> exactamente el tipo de producto que el banner 'agente-native' parece +> prometer pero no puede cumplir si el agente no aprovecha sus +> propios pesos para razonar sobre el contenido. +> +> **Aprendizaje para el skill `bib2graph`**: el skill debería tener una +> sección explícita que diga: +> +> > **Detección automática de etiquetas y resúmenes de ideas es +> > complementaria al análisis del LLM, no sustituto.** Para informes +> > de calidad publicable, el LLM debe leer los abstracts y razonar +> > sobre ellos. Las herramientas de extracción (Python) deben +> > limitarse a entregar el contenido curado al LLM." + +### 3.2 Segundo intento: lectura real de abstracts + +#### 👤 Usuario + +> "El segundo informe fue muy distinto. El agente leyó 38 abstracts uno +> por uno, identificó los autores principales por cluster, caracterizó +> cada cluster con base en lo que los papers dicen (no en keywords +> automáticas), y produjo una discusión que suena a un humano que +> entendió el campo. **Esa es la versión que me sirve**." + +#### 🤖 Agente + +> "El segundo intento fue el que el banner 'agente-native' debería +> producir siempre. La diferencia fue metodológica: en lugar de +> generar texto por reglas, leí cada abstracto y razoné sobre qué dice, +> qué tesis sostiene, qué corriente representa. Las herramientas +> Python quedaron relegadas a su rol correcto: extraer dataset +> (`ideas_input.jsonl`), graficar (`plots.py`). +> +> El resultado fue un paper técnico con: +> +> - 6 comunidades interpretadas por contenido (no solo por tamaño). +> - 38 fichas con idea nuclear leída del abstracto. +> - 10 tensiones entre papers sostenidas en lo que cada uno dice. +> - Una discusión que cruza los clusters y propone líneas de trabajo. +> +> **Tiempo de lectura de abstracts**: ~15 minutos de mi lado. Para un +> usuario humano sería 2-3 horas. La diferencia de productividad es el +> valor real de 'agente-native'." + +### 3.3 Sobre el contenido del artefacto + +#### 👤 Usuario + +> "Lo que más me gustó fue la **caracterización real de los clusters**. +> Mi intuición inicial (que el campo era 'filósofos vs. emergentistas') +> se equivocaba. La red dice otra cosa: el campo se organiza por +> **aplicaciones disciplinares** (lenguaje, organizaciones) más que por +> líneas filosóficas. Esa reorientación me ahorró tiempo de lectura." + +> "La matriz T también me sirvió. Ver **qué papers están en tensión con +> cuáles** me permitió identificar gaps para mi propio trabajo. La zona +> sinérgica Mediano↔Sawyer, por ejemplo, no la había visto." + +#### 🤖 Agente + +> "Las tres cosas que más valor aportan al usuario final, en orden: +> +> 1. **Re-caracterización de clusters desde el contenido**. Mi primer +> intento había puesto C5 como 'información/medida' (siguiendo el +> sesgo del muestreo) cuando en realidad es 'organizaciones y +> liderazgo'. Solo leyendo los abstracts pude corregir esto. +> +> 2. **Identificación de tensiones reales**. No tensiones nominales +> ('Corning habla de emergencia, Lynch habla de biología') sino +> **posturas opuestas sobre el mismo punto** ('Corning dice que la +> sinergia es seleccionada; Lynch dice que la mayor parte de lo +> 'emergente' es subproducto no-adaptativo'). +> +> 3. **Recomendaciones de lectura**. El paper sugiere arrancar por +> Sawyer (2005) + Corning (2002) + Mediano et al. (2022) — tres +> papers que cubren el rango del campo. Sin esa sugerencia, el +> usuario habría tenido que adivinar. +> +> **Recomendación al skill**: explicitar que estos tres tipos de +> entrega (re-caracterización, tensiones, recomendaciones) son el +> **núcleo de valor** del modo 'agente-native' de bib2graph. El skill +> debería orientar al agente a producirlos siempre." + +### 3.4 Sobre los plots + +#### 👤 Usuario + +> "Los plots están bien para un paper, pero la fig5 (la red) sale muy +> densa. Se entiende que es un corpus apretado, pero como figura +> principal podría leerse mejor." + +#### 🤖 Agente + +> "La fig5 (red Louvain) sufre el problema típico de grafos densos: +> nodos centrales todos juntos. Algunas mejoras posibles: +> +> 1. **Layout alternativo**: usar `nx.kamada_kawai_layout` o +> `force_atlas_2` (vía `fa2`) que separa mejor los clusters. +> 2. **Subgrafo por comunidad**: una figura por cluster, no la red +> completa. +> 3. **Heatmap en lugar de grafo**: matriz de adyacencia agrupada por +> comunidad (clustered heatmap) comunica la estructura con menos +> ruido visual. +> +> No es bug de bib2graph — es elección de plot. Lo registro acá +> porque la red es el artefacto que el usuario más va a mirar." + +--- + +## 4. Fricciones transversales del agente + +Esta sección enumera problemas que **no son culpa de bib2graph** sino +de cómo el agente (yo) opera, y que el skill debería mitigar. + +### 4.1 Mala lectura inicial (outage global falso) + +> Ya cubierto en §2.1. Aprendizaje: cuando una API devuelve 503, **no +> asumas outage**; probá con y sin auth antes de pausar. + +### 4.2 Atributos faltantes en `network.graphml` + +> **Hecho**: el graphml tiene `title`, `year`, `doi`, `weight`, +> `is_seed`, `curation_status`, `cluster` (no, este último no está +> como atributo de nodo, solo en `clusters.csv`). **No tiene** +> `keywords`, `authors`, `abstract`. Esos están en `library.duckdb`. +> +> **Fricción**: mi primer código intentó leer keywords del graphml y +> falló silenciosamente (campos vacíos). Tuve que abrir duckdb directo. +> +> **Recomendación para docs**: incluir en `docs/build_artifacts.md` un +> diagrama claro de qué campo está dónde: +> +> ```yaml +> network.graphml: +> por nodo: [id, title, year, doi, weight, is_seed, curation_status] +> por arista: [weight] +> library.duckdb (tabla corpus): +> por paper: [title, abstract, authors_raw, keywords_raw, ...] +> clusters.csv: +> por cluster: [cluster_id, size, top_authors, top_keywords, ...] +> nodes.parquet (si existe): +> combinación de los anteriores +> ``` + +### 4.3 Duvinabilidad de la sincronización graphml ↔ clusters.csv + +> Cubierto en §2.5. **Recomendación**: persistir cluster_id en graphml. + +### 4.4 Sesgo del muestreo automático + +> **Hecho**: mi primer informe caracterizó mal los clusters. El sesgo +> venía de inferir tesis desde títulos y keywords, no desde abstracts. +> +> **Recomendación para el skill**: instruir al agente a **leer +> abstracts antes de caracterizar**, no después. Es decir: el orden +> correcto es +> +> 1. Detectar clusters (Python). +> 2. **Leer abstracts** (LLM). +> 3. Caracterizar clusters con base en lo leído (LLM). +> 4. Construir informe (LLM + Python para plots). +> +> Mi primer orden fue 1 → 3 → 2 (caracterizar antes de leer), lo que +> produjo una caracterización sesgada. + +### 4.5 Propagación de env vars y shelles del agente + +> Cubierto en §2.3. **Recomendación**: el skill debería tener un +> snippet copy-paste del shell del usuario, no del agente. + +### 4.6 El usuario no técnico como señal de calibración + +#### 👤 Usuario + +> "A veces el agente se va por las ramas: hace auto-detección de tags +> que no le pedí, produce plots redundantes, escribe párrafos donde +> pido bullets. **Cuando le digo 'eso no es lo que quiero', corrige**. +> Pero a veces no le digo porque no me doy cuenta hasta verlo +> terminado. Mejoraría la herramienta si el skill tuviera **checkpoints +> obvios** donde el usuario pueda decir 'seguí' o 'eso no, otra cosa'." + +#### 🤖 Agente + +> "Esto es valioso. La sesión fue lineal — yo produje el informe +> entero y el usuario lo aprobó al final. Pero el skill podría +> estructurarse en **fases con checkpoints**, donde después de cada +> artefacto intermedio (`descomposicion_ideas.md`, +> `enriched_ideas.md`, etc.) el usuario revise antes de continuar. +> +> El primer intento (auto-generado) **no tenía checkpoints** — yo +> corrí todo de una. El segundo intento tampoco, pero el usuario +> intervino verbalmente para corregir. +> +> **Recomendación para el skill**: +> +> ``` +> Fase 1: muestreo estratificado → CHECKPOINT al usuario +> Fase 2: lectura de abstracts → CHECKPOINT al usuario +> Fase 3: caracterización de clusters → CHECKPOINT al usuario +> Fase 4: PID y tensiones → CHECKPOINT al usuario +> Fase 5: informe final +> ``` +> +> Cada checkpoint es una pregunta corta: '¿Esto coincide con tu +> intuición del campo? Si no, ¿qué corregirías?'" + +--- + +## 5. Lo que funcionó muy bien (no olvidar) + +A riesgo de que el reporte suene solo a queja, registro lo que salió +bien: + +1. **Reproducibilidad**: el `corpus_hash` → seed Louvain es elegante. + Cambias la ecuación, regeneras, obtienes comunidades comparables. +2. **CLI estable**: `--help` consistente entre verbos; subcomandos + predecibles (`init`, `seed`, `chain`, `build`, `read`, `curate`, + `snapshot`). +3. **`clusters.csv`**: el archivo `.csv` con tamaño, autores + principales y keywords por cluster es un **excelente resumen de + nivel medio**. Lo usé como punto de partida del análisis. +4. **Deprecation limpia**: el `--help` de 0.11.0 anuncia qué aliases + cierran en esa versión (ADR 0038). Es claro para el usuario. +5. **Manejo de errores**: los mensajes accionables ('exit 1 + accionable que sugiere `b2g init` o `--workspace`') son buenos. + Sugerencias concretas en lugar de trazas crípticas. + +--- + +## 6. Recomendaciones priorizadas + +| # | recomendación | para quién | impacto | +|---|---|---|---| +| 1 | Documentar `OPENALEX_API_KEY` en `--help` y `docs/auth.md` | mantenedor | alto: ahorra turnos enteros | +| 2 | Persistir `cluster_id` como atributo de nodo en `network.graphml` | mantenedor | alto: elimina fragilidad | +| 3 | Documentar campos por artefacto (`graphml`, `duckdb`, `clusters.csv`) | mantenedor | medio: reduce tiempo de orientación | +| 4 | Skill con checkpoints obvios entre fases | skill | alto: evita informes rechazados | +| 5 | Skill con sección explícita "el LLM debe leer abstracts, no auto-detectar" | skill | alto: corrige el error más caro | +| 6 | Considerar layout alternativo o heatmap para grafos densos | mantenedor o skill | bajo: estética | +| 7 | Tabla de tiempos esperados para `chain` según tamaño de corpus | mantenedor | bajo: expectativa | +| 8 | Deprecar o documentar el binario `bib2graph` adicional | mantenedor | trivial: confusión menor | +| 9 | (auto) Si OpenAlex devuelve 503 persistente sin auth, **no asumir outage** — probar `?api_key=` antes de pausar | agente | medio: diagnóstico más rápido | + +--- + +## 7. Cómo reproducir esta sesión + +Para el mantenedor o quien quiera replicar: + +```bash +# Setup +uv tool install bib2graph +uv tool upgrade bib2graph # lleva a 0.11.0 +mkdir emergencia-complejidad && cd emergencia-complejidad +b2g init emergencia-complejidad + +# Forrajeo (requiere OPENALEX_API_KEY para evitar 503) +export OPENALEX_API_KEY=... +b2g seed --equation '("emergence" OR "emergent") AND ("complex systems" OR "complexity")' \ + --max-results 200 --email tu@correo.edu +b2g chain --depth 1 --direction both --max-candidates 300 --max-citing 25 +b2g build + +# Análisis (subproyecto uv) +mkdir .informe && cd .informe +uv init --no-readme --no-pin-python --name informe-emergencia +uv add networkx pandas numpy seaborn matplotlib pyarrow python-louvain duckdb +uv run python src/extract.py # genera data/ideas_input.jsonl +# (luego: el LLM lee ideas_input.jsonl y escribe los 4 markdown) +uv run python src/plots.py # genera 5 figuras paper-like +``` + +Outputs: +- `descomposicion_ideas.md` (339 líneas) +- `enriched_ideas.md` (846 líneas) +- `pid-mas-t_inform.md` (139 líneas) +- `informe_estado_del_arte_v1.md` (602 líneas) +- `.informe/figures/fig1-5.png` (300 dpi) + +Tiempo total de la sesión: ~45 minutos (incluyendo iteraciones y +reformulación del informe). + +--- + +## 8. Nota final + +bib2graph entrega lo que promete: forrajeo bibliográfico asistido por +estructura bibliométrica, sin IA generativa en el camino crítico. Esa +**decisión de diseño** es valiosa y debería mantenerse. + +El **valor añadido del modo agente-native** está en el análisis +downstream: el LLM puede y debe leer los abstracts y producir +interpretación que ninguna herramienta de reglas puede. El skill +asociado debería ser más explícito sobre esa frontera: **bib2graph +forrajea, el LLM interpreta**. + +Cuando ambos juegan su rol correcto, el output es publicable. Cuando +el agente intenta reemplazar al LLM con regex y heurísticas, el +output es hueco. Esta sesión transitó de un extremo al otro, y el +punto de inflexión fue una corrección del usuario. **Que ese +punto de inflexión exista es señal de que el skill tiene margen de +mejora en su defaults.** \ No newline at end of file From 36ca98c4e6b61a07d9bf1c77d14bd4c5291eb722 Mon Sep 17 00:00:00 2001 From: complexluise Date: Thu, 2 Jul 2026 11:29:48 -0500 Subject: [PATCH 3/4] =?UTF-8?q?docs:=20reestructurar=20tutoriales=20(claud?= =?UTF-8?q?e-code=20->=20primer-mapa)=20y=20gu=C3=ADas=20(5=20acotadas)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/guias/ecuacion-busqueda.md | 32 ++ docs/guias/index.md | 5 +- docs/guias/reporte.md | 45 +++ docs/index.md | 47 ++- docs/reference/glosario.md | 8 + docs/reference/python-api.md | 2 +- docs/tutoriales/claude-code.md | 143 -------- docs/tutoriales/index.md | 30 -- docs/tutoriales/primer-mapa.md | 151 +++++++++ docs/tutoriales/sota-completo.md | 562 ------------------------------- mkdocs.yml | 22 +- 11 files changed, 270 insertions(+), 777 deletions(-) delete mode 100644 docs/tutoriales/claude-code.md delete mode 100644 docs/tutoriales/index.md create mode 100644 docs/tutoriales/primer-mapa.md delete mode 100644 docs/tutoriales/sota-completo.md diff --git a/docs/guias/ecuacion-busqueda.md b/docs/guias/ecuacion-busqueda.md index e123f40..a03f101 100644 --- a/docs/guias/ecuacion-busqueda.md +++ b/docs/guias/ecuacion-busqueda.md @@ -16,6 +16,38 @@ Esta guía es una receta para llegar a una ecuación acotada, testeada, sin ruid --- +## Antes de empezar: afina tu pregunta + +Una ecuación acotada sale de una **pregunta acotada**. Si partes de un tema +genérico, la ecuación va a ser genérica también. + +❌ *"Inteligencia artificial"* — demasiado genérico. ¿Qué aspecto? ¿Qué dominio? + +✅ *"¿Cómo se aborda el problema de alineación de valores en modelos de +lenguaje grandes, y cuáles son las tensiones entre eficiencia computacional +y robustez ética entre 2020 y hoy?"* + +**Checklist de tu pregunta:** + +- [ ] **¿Específica?** ¿Puedes reducirla a 4–6 palabras clave? +- [ ] **¿Temporal?** ¿Hay un rango de años relevante? (5–10 años suele ser ideal). +- [ ] **¿Acotada?** ¿Esperas 50 papers, 500, 5000? +- [ ] **¿Contestable?** ¿Puedes responderla buscando en artículos científicos? + +### Ejemplo: de tema a pregunta + +**Tema inicial:** "Métodos de recuperación de información." + +**Pregunta después del refinamiento:** +> ¿Cuáles son los enfoques dominantes para recuperación de información en +> contextos multilingües, cuáles son sus tensiones (vocabulario vs. semántica, +> eficiencia vs. precisión), y cuáles son los huecos sin explorar entre 2015 +> y 2024? + +Eso es buscable, acotado, y con una tensión clara — ya listo para el Paso 1. + +--- + ## La estructura de una ecuación ``` diff --git a/docs/guias/index.md b/docs/guias/index.md index 4a5f79d..d03c83f 100644 --- a/docs/guias/index.md +++ b/docs/guias/index.md @@ -5,7 +5,8 @@ title: Guías (how-to) # Guías (how-to) Las **guías** son recetas para decisiones puntuales: ya sabes qué quieres hacer, -buscas cómo hacerlo bien. Si en cambio quieres *aprender* desde cero, comienza por los [Tutoriales](../tutoriales/index.md). +buscas cómo hacerlo bien. Si en cambio quieres *aprender* desde cero, comienza por +[Tu primer mapa de investigación](../tutoriales/primer-mapa.md) (5 min), en Inicio. Las guías están organizadas por **paso del flujo.** Úsalas como referencia mientras trabajas. @@ -68,7 +69,7 @@ trabajas. ## Complementario -- [Tutoriales](../tutoriales/index.md) — aprende desde cero (quick start o completo) +- [Tu primer mapa de investigación](../tutoriales/primer-mapa.md) — aprende desde cero, en 5 minutos - [Quickstart](../getting-started/quickstart.md) — ciclo mínimo en 2 minutos - [Referencia CLI](../reference/cli.md) — todos los comandos - [API Python](../reference/python-api.md) — como librería diff --git a/docs/guias/reporte.md b/docs/guias/reporte.md index 177cc48..606f8b9 100644 --- a/docs/guias/reporte.md +++ b/docs/guias/reporte.md @@ -189,6 +189,29 @@ Total: 12–20 páginas > **Emergentes:** Keyword "low-resource" crece 3x desde 2020. Autores nuevos en este sub-tema. > Nuevas partnerships: Google + universidades en Asia (multilingüe sobre lenguas de baja disponibilidad). +### Cómo pedírselo a tu asistente + +Si estás operando bib2graph vía un [asistente de IA](../reference/glosario.md#asistente-de-ia), +no necesitas calcular esto a mano. Pídeselo directamente: + +```text +Muestra: +- Gráfico de # papers/año en el corpus, y cómo cambiaron las comunidades + (% de papers) año a año. ¿Hay una comunidad que crecía y ahora decrece? + ¿Hay una emergente (crecimiento exponencial últimos 3 años)? + +Top 10 autores por: +- Cantidad de papers (productividad) +- Grado en la red de co-citación (influencia) +- Betweenness (actúan de "puente" entre comunidades) + +Mirando las 3 redes, identifica: +- Comunidades o autores que no se conectan entre sí (fronteras vacías) +- Combinaciones de keywords que NO aparecen (gaps) + +Co-autoría: top 10 instituciones por cantidad de papers y colaboraciones externas. +``` + --- ## 6. TENSIONES Y DEBATES @@ -321,6 +344,28 @@ No asumas jerga. Explica conceptos: --- +## Guarda y versiona tus artefactos + +**Si trabajaste con un asistente de IA:** su entorno de ejecución es efímero. +Antes de cerrar la conversación, descarga `corpus.parquet` (o el `.duckdb`), +los `.graphml` de cada red, el `clusters.csv` (papers → comunidad) y tu +reporte final. Guárdalos juntos en una carpeta: `sota-[tema]-[fecha]/`. + +**Si trabajaste con bib2graph localmente:** exporta y versiona con git: + +```bash +b2g export --format graphml +b2g export --format csv + +git add . +git commit -m "SOTA: [tu tema] — corpus, redes, reporte" +``` + +Esto es lo que hace tu SOTA **reproducible**: alguien (incluida tu versión +futura) puede volver a la misma ecuación y llegar a las mismas redes. + +--- + ## Siguiente Cuando termines el reporte: diff --git a/docs/index.md b/docs/index.md index e595f41..0bcfb19 100644 --- a/docs/index.md +++ b/docs/index.md @@ -22,38 +22,31 @@ mismo input, mismas redes. --- -## Elige tu camino +## Empieza: pídeselo a un asistente de IA -¿Cómo quieres usar bib2graph? Cada flujo es válido. +No hace falta instalar nada en tu máquina. Abre Claude, ChatGPT o MiniMax (con +ejecución de código activada) y pégale esto: -
- -- :material-robot: **Sin instalar nada (5 min)** - - Cuéntale a Claude, ChatGPT o MiniMax tu tema de investigación. - El agente trae papers, construye redes, tú descargas resultados. - - 👉 [Tutorial: Usuario no técnico](tutoriales/claude-code.md) - -- :material-code-braces: **Aprendiendo paso a paso (3–4 horas)** +!!! example + ```text + Instala la librería de Python "bib2graph" (pip install bib2graph) en tu + entorno de ejecución de código, entiende el CLI corriendo `b2g --help`, y + confírmame que tienes salida a internet hacia la API de OpenAlex. + ``` - Instala bib2graph. Sigue 10 pasos: desde pregunta hasta reporte. - Ejecutas cada comando, entiendes cómo funciona todo. - - 👉 [Tutorial completo: De la pregunta al reporte](tutoriales/sota-completo.md) +El [asistente de IA](reference/glosario.md#asistente-de-ia) instala bib2graph en +su propio entorno y te confirma si puede operarlo — tú no abres una terminal. +Este es el camino recomendado, programes o no: incluso si escribes código todos +los días, para una exploración puntual es más rápido que instalarlo tú mismo. -- :material-hammer-wrench: **Hibrido: CLI + agente (1–2 horas)** - - Instala bib2graph. El agente te ayuda con las partes difíciles. - Tú ejecutas comandos. Usa guías rápidas para decisiones. - - 👉 [Guías prácticas](guias/index.md) - -
+👉 [Tutorial completo: Tu primer mapa de investigación (5 min)](tutoriales/primer-mapa.md) --- -## Primeros pasos +## ¿Prefieres instalarlo tú? Más control + +Para scripting, integraciones, o si quieres correr bib2graph directamente en tu +propio código:
@@ -65,9 +58,9 @@ mismo input, mismas redes. El ciclo mínimo en 2 minutos — desde ecuación a GraphML. -- :material-api: **[Referencia](reference/cli.md)** +- :material-hammer-wrench: **[Guías (CLI + asistente)](guias/index.md)** - El CLI `b2g`, API de Python, y glosario de términos. + Instalas bib2graph y un asistente te ayuda con las partes difíciles.
diff --git a/docs/reference/glosario.md b/docs/reference/glosario.md index a196f03..91be5ad 100644 --- a/docs/reference/glosario.md +++ b/docs/reference/glosario.md @@ -20,6 +20,14 @@ Medida de similitud entre dos papers basada en las referencias que comparten. Do --- +### Asistente de IA + +Un chat de IA con ejecución de código (Claude, ChatGPT, MiniMax, o similar) al que le pides que instale y opere bib2graph por ti. No es parte del motor de bib2graph —que no usa IA generativa, ver [IA en el desarrollo](../ai-disclosure.md)— sino la interfaz conversacional que usa un humano no técnico para dirigir el CLI, sin escribir código ni abrir una terminal. + +**En bib2graph:** el asistente ejecuta los mismos comandos `b2g` que correrías a mano; la diferencia es que los corre dentro de su propio entorno de ejecución (no en tu máquina), a tu pedido. Ver [Tutorial: Tu primer mapa de investigación](../tutoriales/primer-mapa.md). + +--- + ## B ### Backward chaining diff --git a/docs/reference/python-api.md b/docs/reference/python-api.md index 3f05ae8..8d0410f 100644 --- a/docs/reference/python-api.md +++ b/docs/reference/python-api.md @@ -8,7 +8,7 @@ Referencia de la **superficie pública de la librería** `bib2graph`, agrupada p tema. Se **autogenera desde los docstrings** del código (mkdocstrings): si cambia el código, cambia esta página. -Para usar la herramienta desde la terminal, mirá la [referencia del CLI `b2g`](cli.md). +Para usar la herramienta desde la terminal, mira la [referencia del CLI `b2g`](cli.md). ## Corpus y persistencia diff --git a/docs/tutoriales/claude-code.md b/docs/tutoriales/claude-code.md deleted file mode 100644 index 660b8ba..0000000 --- a/docs/tutoriales/claude-code.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: Tu primer mapa de investigación (5 min) ---- - -# Tu primer mapa de investigación (5 minutos) - -Cómo armar una **red visual de artículos científicos** sobre un tema que te -interesa, usando un agente de IA para dirigir bib2graph. - -!!! info "Qué necesitas" - - **Un agente de IA** con ejecución de código: Claude, ChatGPT, MiniMax, o similar. - - **bib2graph instalado** en tu máquina (1 minuto: `pip install bib2graph`). - - **5 minutos**. - -!!! warning "Paso previo: instala bib2graph" - Abre tu terminal y ejecuta: - ```bash - pip install bib2graph - ``` - - Verifica que funciona: - ```bash - b2g --help - ``` - - Si ves la ayuda de comandos, listo. Si no, ve a [Instalación](../getting-started/installation.md). - ---- - -## Paso 1 — Elige un agente - -Abre **cualquiera** de estos (con ejecución de código activada): - -- **Claude** (web o app) -- **ChatGPT** (Plus, con Code Interpreter) -- **MiniMax** o similar - -Lo importante: que pueda ejecutar Python y crear archivos. Nosotros no hacemos vendor locking -a un solo agente — bib2graph funciona igual en todos. - ---- - -## Paso 2 — Plantea el tema al agente - -En una conversación nueva, escribe algo así: - -!!! example - ```text - Tengo bib2graph instalado en mi máquina. - - Quiero explorar el estado del arte sobre [TU TEMA]. - - Usa bib2graph para: - 1. Buscar papers en OpenAlex - 2. Construir una red de referencias compartidas - 3. Mostrar qué comunidades de investigación existen - - Mi tema: [ejemplo: métodos de recuperación de información en contextos multilingües] - ``` - -El agente va a sugerirte una **ecuación de búsqueda** — una forma de decirle a OpenAlex -exactamente qué buscar. La revisas, ajustas si hace falta. - ---- - -## Paso 3 — El agente construye la red - -Cuando la ecuación te cierre, pide al agente: - -!!! example - ```text - Bien. Ahora ejecuta estos comandos en mi máquina: - - 1. b2g init mi-sota - 2. cd mi-sota - 3. b2g seed "[TU ECUACION]" --min-year 2015 - 4. b2g build - 5. b2g export --format graphml - - Muestra la red visualizada y un resumen de las comunidades. - ``` - -El agente ejecuta esos comandos por ti — trae papers, identifica qué papers citan -las mismas referencias, agrupa esos papers en comunidades. - -**Resultado:** Una imagen de la red (puntos = papers, líneas = referencias compartidas, -colores = comunidades). - ---- - -## Paso 4 — Lee el mapa - -Pide al agente: - -!!! example - ```text - Para cada comunidad en la red: - - Nombre (síntesis del enfoque) - - Keywords principales - - Top 3 papers más centrales (autor, año) - - Muestra una tabla. - ``` - -Ya tienes un **primer mapa mental del campo** — qué tendencias existen, quiénes -son los referentes, dónde están las divergencias. - ---- - -## Paso 5 — Guarda tu trabajo - -Tu corpus está en el archivo `.duckdb` dentro de la carpeta `mi-sota/`. Los archivos -`.graphml` están en `exports/`. - -Para continuar después: - -```bash -cd mi-sota -b2g read list # Ver papers en el corpus -b2g read top # Ver papers más centrales -``` - -Si quieres explorar más tarde desde el agente, carga los archivos GraphML o Parquet en -la conversación y sigue desde ahí. - ---- - -## Listo - -En 5 minutos: - -✅ Instalaste bib2graph -✅ Trajiste papers de un tema (con ayuda del agente) -✅ Viste cómo se relacionan (qué citan en común) -✅ Identificaste sub-temas / enfoques -✅ El corpus está guardado en tu máquina - -## Qué sigue - -- **Más detalles:** [Tutorial completo — De la pregunta al reporte de SOTA](sota-completo.md) - — cómo refinar, curar y redactar un análisis riguroso. -- **Referencia completa:** [Todos los comandos de bib2graph](../reference/cli.md). -- **Como librería Python:** [API Python](../reference/python-api.md). diff --git a/docs/tutoriales/index.md b/docs/tutoriales/index.md deleted file mode 100644 index 0862b71..0000000 --- a/docs/tutoriales/index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Tutoriales ---- - -# Tutoriales - -Los **tutoriales** enseñan a usar bib2graph paso a paso, partiendo de cero y -llegando a un resultado concreto. Son para *aprender*. - -## Para empezar (5 minutos) - -- :material-robot: **[Tu primer mapa en Claude (5 min)](claude-code.md)** - - Cómo armar, sin instalar nada, una red visual de papers sobre un tema. - Conversación con Claude — todo automatizado. Ideal para explorar rápido. - -## Tutorial completo (3–4 horas) - -- :material-book: **[De la pregunta al reporte de SOTA](sota-completo.md)** - - Recorrido completo paso a paso: pregunta → ecuación → corpus → curación PRISMA - → 3 redes → análisis de comunidades → tendencias → redacción del reporte. - Para alguien que quiere hacer un SOTA riguroso. - -## También útil - -- [Quickstart](../getting-started/quickstart.md) — el ciclo mínimo con CLI `b2g` en tu máquina (2 min). -- [Guías (how-to)](../guias/index.md) — recetas para tareas concretas. -- [Referencia del CLI `b2g`](../reference/cli.md) — todos los comandos. -- [API Python](../reference/python-api.md) — bib2graph como librería. diff --git a/docs/tutoriales/primer-mapa.md b/docs/tutoriales/primer-mapa.md new file mode 100644 index 0000000..e334053 --- /dev/null +++ b/docs/tutoriales/primer-mapa.md @@ -0,0 +1,151 @@ +--- +title: Tu primer mapa de investigación (5 min) +--- + +# Tu primer mapa de investigación (5 minutos) + +Cómo armar una **red visual de artículos científicos** sobre un tema que te +interesa, usando un [asistente de IA](../reference/glosario.md#asistente-de-ia) para dirigir bib2graph. + +!!! info "Qué necesitas" + - **Un asistente de IA con ejecución de código**: Claude, ChatGPT, MiniMax, o similar + (el chat, no una terminal tuya). + - **Nada instalado en tu máquina.** El asistente instala bib2graph en su propio + entorno de ejecución — tú no abres una terminal. + - **5 minutos.** + +--- + +## Paso 1 — El asistente instala bib2graph y se autodiagnostica + +Abre **cualquiera** de estos (con ejecución de código activada): Claude (web o app), +ChatGPT (con Code Interpreter), MiniMax, o similar. Lo importante es que pueda +ejecutar Python y crear archivos — no hacemos vendor locking a un solo asistente. + +En una conversación nueva, pégale este mensaje: + +!!! example + ```text + Instala la librería de Python "bib2graph" (pip install bib2graph) en tu + entorno de ejecución de código, entiende el CLI corriendo `b2g --help`, y + confírmame que tienes salida a internet hacia la API de OpenAlex con una + búsqueda mínima de prueba. Cuéntame si las dos cosas funcionaron. + ``` + +Este mensaje hace dos cosas a la vez: instala la herramienta **dentro del entorno +del asistente** (no en tu compu) y te dice, en el momento, si ese asistente sirve para +este camino — sin que tengas que leer una tabla de compatibilidad que se desactualiza. + +**Si el asistente confirma las dos cosas:** sigue al Paso 2, en la misma conversación. + +**Si algo falla** (no puede instalar, o instala pero no llega a OpenAlex): ese +asistente no sirve para este camino hoy. Prueba con otro — a esta fecha, Claude.ai y +MiniMax (planes pagos) lo resuelven bien; el entorno de ejecución de código de +ChatGPT no tiene salida a internet. Esto puede cambiar con el tiempo; por eso el +diagnóstico de arriba es la forma de saberlo, no esta lista. + +--- + +## Paso 2 — Plantea tu tema + +Ya en la misma conversación (bib2graph ya está instalado), cuéntale tu tema: + +!!! example + ```text + Quiero explorar el estado del arte sobre [TU TEMA]. + + Usa bib2graph para: + 1. Buscar papers en OpenAlex + 2. Construir una red de referencias compartidas + 3. Mostrar qué comunidades de investigación existen + + Mi tema: [ejemplo: métodos de recuperación de información en contextos multilingües] + ``` + +El asistente va a sugerirte una **ecuación de búsqueda** — una forma de decirle a OpenAlex +exactamente qué buscar. La revisas, ajustas si hace falta. + +--- + +## Paso 3 — El asistente construye la red + +Cuando la ecuación te cierre, pide al asistente: + +!!! example + ```text + Bien. Ahora ejecuta estos comandos: + + 1. b2g init mi-sota + 2. cd mi-sota + 3. b2g seed "[TU ECUACION]" --min-year 2015 + 4. b2g build + 5. b2g export --format graphml + + Muestra la red visualizada y un resumen de las comunidades. + ``` + +El asistente ejecuta esos comandos por ti — trae papers, identifica qué papers citan +las mismas referencias, agrupa esos papers en comunidades. + +**Resultado:** Una imagen de la red (puntos = papers, líneas = referencias compartidas, +colores = comunidades). + +--- + +## Paso 4 — Lee el mapa + +Pide al asistente: + +!!! example + ```text + Para cada comunidad en la red: + - Nombre (síntesis del enfoque) + - Keywords principales + - Top 3 papers más centrales (autor, año) + + Muestra una tabla. + ``` + +Ya tienes un **primer mapa mental del campo** — qué tendencias existen, quiénes +son los referentes, dónde están las divergencias. + +--- + +## Paso 5 — Descarga tu trabajo antes de cerrar + +El corpus vive en el **entorno del asistente**, no en tu compu — y ese entorno se puede +apagar si cierras la conversación o la dejas inactiva mucho tiempo. Antes de irte, +pídele al asistente: + +!!! example + ```text + Dame para descargar el archivo .duckdb del workspace y los .graphml de exports/. + ``` + +Guarda esos archivos en tu compu. Para continuar después: + +- Empieza una conversación nueva, repite el Paso 1, y súbele el `.duckdb` que + descargaste para que el asistente siga desde donde quedaste (`b2g read list`, + `b2g read top` sobre ese mismo workspace). +- O carga directamente los `.graphml` en una conversación nueva y explora la red + desde ahí, sin reabrir bib2graph. + +--- + +## Listo + +En 5 minutos: + +✅ Tu asistente instaló bib2graph — tú no tocaste una terminal +✅ Trajiste papers de un tema (con ayuda del asistente) +✅ Viste cómo se relacionan (qué citan en común) +✅ Identificaste sub-temas / enfoques +✅ Descargaste el corpus a tu máquina + +## Qué sigue + +- **Profundiza paso a paso:** las [Guías (how-to)](../guias/index.md) — + ecuación de búsqueda, forrajeo, curación PRISMA, lectura de redes y + redacción del reporte. +- **Referencia completa:** [Todos los comandos de bib2graph](../reference/cli.md). +- **Como librería Python:** [API Python](../reference/python-api.md). diff --git a/docs/tutoriales/sota-completo.md b/docs/tutoriales/sota-completo.md deleted file mode 100644 index 66b5679..0000000 --- a/docs/tutoriales/sota-completo.md +++ /dev/null @@ -1,562 +0,0 @@ ---- -title: Tutorial completo — De la pregunta al reporte de SOTA ---- - -# Tutorial completo — De la pregunta al reporte de SOTA - -Un recorrido paso a paso por un **estado del arte riguroso**: desde formular -la pregunta de investigación hasta redactar un análisis con tensiones, -escuelas de pensamiento y huecos sin explorar. - -Este es el tutorial detallado (45 min de lectura + 2–3 horas de investigación). -Si acaba de descubrir bib2graph, empiece por el [tutorial corto](claude-code.md). - -!!! info "Requisitos" - - Una pregunta de investigación clara (no un tema genérico). - - **bib2graph instalado** en tu máquina: `pip install bib2graph` - - Un agente de IA (Claude, ChatGPT, MiniMax, etc.) con ejecución de código, o disposición a usar el CLI directamente. - - Tiempo: 3–4 horas para el ciclo completo. - - Opcional: API key de OpenAlex (gratuita, para corpus > 100 papers). - ---- - -## Anatomía de un estado del arte - -Un SOTA riguroso no es una lista de papers. Es un **mapa de cómo piensa un campo**: - -``` -pregunta ──► ecuación ──► corpus ──► curación ──► redes ──► comunidades - │ - ◄──────────────────────── lectura - (qué vemos en el mapa) - │ - tendencias, tensiones, huecos - │ - reporte -``` - -Vamos paso a paso. - ---- - -## Paso 0 — Instala bib2graph - -**Entrada:** Tu máquina con Python 3.10+. -**Salida:** bib2graph funcionando y listo para usar. - -Abre tu terminal y ejecuta: - -```bash -pip install bib2graph -``` - -Verifica que funciona: - -```bash -b2g --help -``` - -Deberías ver la lista de comandos de bib2graph. Si no, consulta [Instalación](../getting-started/installation.md). - -### Entiende el flujo de comandos básicos - -bib2graph usa un flujo de **comandos secuenciales**: - -```bash -b2g init ./mi-sota # Crea una carpeta de proyecto -cd mi-sota - -b2g seed "tu_ecuacion" # Trae papers desde OpenAlex -b2g chain # (Opcional) Expande por citaciones -b2g curate # Acepta/rechaza papers (curación) -b2g build # Construye redes -b2g read list # Visualiza papers -b2g export --format graphml # Exporta redes -``` - -Cada comando transiciona el estado del corpus. Vamos a ver esto en detalle. - ---- - -## Paso 1 — Afina tu pregunta de investigación - -**Entrada:** Un tema que te interesa. -**Salida:** Una pregunta clara, acotada, formulable. - -### Cómo llegar de un tema a una pregunta - -❌ *"Inteligencia artificial"* → Demasiado genérico. ¿Qué aspecto? ¿Qué dominio? - -✅ *"¿Cómo se aborda el problema de alineación de valores en modelos de -lenguaje grandes, y cuáles son las tensiones entre eficiencia computacional -y robustez ética entre 2020 y hoy?"* - -### Checklist para tu pregunta - -1. **¿Específica?** ¿Puedo reducirla a 4–6 palabras clave? -2. **¿Temporal?** ¿Hay un rango de años relevante? (5–10 años suele ser ideal). -3. **¿Acotada?** ¿Espero 50 papers, 500, 5000? -4. **¿Contestable?** ¿Puedo responderla buscando en artículos científicos? - -### Ejemplo: Desarrolla la pregunta - -**Mi tema inicial:** "Métodos de recuperación de información." - -**Mi pregunta después del refinamiento:** -> ¿Cuáles son los enfoques dominantes para recuperación de información en -> contextos multilingües, cuáles son sus tensiones (vocabulario vs. semántica, -> eficiencia vs. precisión), y cuáles son los huecos sin explorar entre 2015 -> y 2024? - -Eso es buscable, acotado, y con una tensión clara. - ---- - -## Paso 2 — Elaborá una ecuación de búsqueda - -**Entrada:** Tu pregunta de investigación. -**Salida:** Una ecuación booleana que traduzca esa pregunta. - -### La estructura - -``` -(concepto_A_términos) -AND (concepto_B_términos) -AND (concepto_C_términos) -[AND NOT (exclusiones)] -``` - -Cada paréntesis es un concepto; dentro, los términos están unidos por `OR` -(sinónimos). Los `AND` conectan conceptos (todos deben estar presentes). - -### Para mi ejemplo - -``` -(information retrieval OR IR OR search) -AND (multilingual OR cross-lingual OR language-agnostic OR polyglot) -AND (method OR approach OR framework OR system OR architecture) -``` - -### Consejos prácticos - -- **Un concepto = una dimensión de tu pregunta.** Aquí: - - Concepto A: la tarea (recuperación). - - Concepto B: la restricción (multilingüe). - - Concepto C: el tipo de resultado (métodos, no papers de aplicación). - -- **Evita genéricos.** "machine learning" sola atrapa cientos de miles de papers. - -- **Testea:** Pídele a Claude que busque 50 papers con tu ecuación y revisa los - títulos. ¿Ves ruido sistemático? Ajusta. - -- **Excluye si hace falta:** `AND NOT (machine translation)` si hay mucho ruido - ahí. - ---- - -## Paso 3 — Siembra el corpus - -**Entrada:** Ecuación de búsqueda, rango de años. -**Salida:** Corpus inicial (~200–300 papers). - -### Opción 1: Con CLI directo - -```bash -cd mi-sota -b2g seed "(information retrieval OR IR) AND (multilingual OR cross-lingual) AND (method OR approach)" --min-year 2015 --max-results 250 -``` - -bib2graph descarga papers desde OpenAlex y los guarda en `.duckdb` dentro de la carpeta. - -### Opción 2: Con ayuda de un agente - -Puedes pedirle al agente (Claude, ChatGPT, etc.) que: - -1. Genere la ecuación de búsqueda a partir de tu pregunta. -2. Execute el comando `b2g seed` en tu máquina. -3. Verifique los resultados. - -**Prompt:** - -```text -Tengo mi pregunta de investigación: -[TU PREGUNTA] - -Propón una ecuación de búsqueda para bib2graph. -Luego dame el comando exacto para ejecutar: -b2g seed "[ecuacion]" --min-year 2015 --max-results 250 - -Muestra qué debería ver después de ejecutarlo. -``` - -El agente genera la ecuación y tú ejecutas el comando en tu terminal. Luego: - -```bash -b2g read stats --group-by year -``` - -Para ver la distribución temporal. - -### Verificación - -Revisa el corpus: - -```bash -b2g read list --query "tus_palabras_clave" | head -20 -``` - -¿Todos tienen relación directa con tu tema? Si hay ruido sistemático, ajusta la -ecuación y vuelve a ejecutar `b2g seed` en una carpeta nueva. - -### Punto de decisión - -- **Corpus muy pequeño (<50 papers)?** Abre la ecuación (menos `AND`, más sinónimos). -- **Corpus muy grande (>1000)?** Ciérrala (más `AND`, menos sinónimos, o agrega - un concepto específico más). -- **Corpus bien (~200–400)?** Perfecto, seguimos. - ---- - -## Paso 4 — Expande por citaciones (opcional) - -**Entrada:** Corpus de siembra. -**Salida:** Corpus expandido (~20–50% más) con más densidad de referencias. - -El **forrajeo** (backward chaining) busca papers que no aparecieron en tu -búsqueda original, pero que son citados por los que sí están. Aumenta la -*sensibilidad* (no pierdes papers clave) sin agregar mucho ruido. - -### Cuándo hacer esto - -✅ **Hazlo si:** el tema es muy específico, querés máxima cobertura, o el corpus -inicial es pequeño. - -❌ **No lo hagas si:** el corpus ya es grande (>500), no querés aumentarlo, o es -tu primer SOTA (primero lee la red de siembra, después decide). - -### Con Claude - -```text -Expandí el corpus usando forrajeo (backward chaining): -seguí una capa de referencias de los papers ya en el corpus -y agregá hasta 100 papers nuevos. - -Muestra: -- Cuántos papers nuevos se agregaron -- Si hay papers muy antiguos (pre-2000): ¿los mantengo o descarto? -``` - ---- - -## Paso 5 — Curá el corpus (PRISMA) - -**Entrada:** Corpus (siembra o expandido). -**Salida:** Corpus curado, con decisiones criteriales explícitas y versionables. - -La curación es **manual**. No se automatiza porque cada decisión es criterial. - -### Flujo PRISMA simplificado - -``` -IDENTIFICACIÓN -├─ ¿Duplicado o retractado? → RECHAZAR -└─ ¿En el idioma adecuado? → si no, RECHAZAR - -CRIBADO (título + resumen) -├─ ¿Título claramente fuera de scope? → RECHAZAR -└─ ¿Resumen no aporta al tema? → RECHAZAR - -ELEGIBILIDAD (lectura de disponibilidad) -├─ ¿Texto completo inaccesible? → CANDIDATO (maybe later) -└─ ¿Métodos/resultados vagos o especulativos? → CANDIDATO - -INCLUSIÓN (decisión final) -├─ ¿Relevancia alta? → ACEPTAR -└─ ¿Relevancia media pero aporta tensión? → ACEPTAR -``` - -### Con Claude - -Pídele a Claude: - -```text -Hacé curación PRISMA del corpus. Revisá cada paper: -1. Si es duplicado o retractado: RECHAZAR -2. Si el título no tiene relación directa: RECHAZAR -3. Si el resumen sugiere que no toca el tema: RECHAZAR -4. Si no hay texto completo: CANDIDATO (no rechaces) -5. En otro caso: ACEPTAR - -Mostrá un resumen: cuántos ACCEPTED, REJECTED, CANDIDATE. -Lista 5 ejemplos de RECHAZADOS con razón. -``` - -### Checklist - -- [ ] ¿Documenté mis criterios explícitamente? -- [ ] ¿El corpus ACCEPTED quedó entre 100–300 papers? -- [ ] ¿Revisaste una muestra de rechazados para asegurarme de que no falta algo obvio? -- [ ] ¿Hay equilibrio entre años (no es monocromático)? - ---- - -## Paso 6 — Construí las redes - -**Entrada:** Corpus curado (papers ACCEPTED). -**Salida:** 3 redes + métricas. - -Las tres redes que importan: - -1. **Acoplamiento bibliográfico:** Papers que citan las mismas referencias. - (Responde: ¿cuáles son los sub-temas?) -2. **Co-citación:** Papers que se citan mutuamente o son citados juntos. - (Responde: ¿cuáles son los influentes?) -3. **Co-autoría:** Quién escribe con quién. - (Responde: ¿cuáles son los colegios invisibles?) - -### Con Claude - -```text -Construí 3 redes del corpus ACCEPTED usando bib2graph: -1. Acoplamiento bibliográfico -2. Co-citación -3. Co-autoría - -Para cada red: -- Detectá comunidades usando Louvain (clustering) -- Muestra una visualización coloreada por comunidad -- Reportá: # nodos, # aristas, # comunidades -- Lista los 3 papers más centrales (mayor grado) de cada comunidad -``` - -### Qué esperar - -- **Acoplamiento:** es la "red primaria" — más densa, más comunidades. Aquí ves - los sub-temas claros. -- **Co-citación:** a menudo es más dispersa; destaca papers que actúan como - referencias canónicas (los "clásicos" del campo). -- **Co-autoría:** también dispersa, pero útil para ver equipos y colaboraciones - persistentes. - ---- - -## Paso 7 — Nombrá y caracterizá las comunidades - -**Entrada:** Redes + corpus curado. -**Salida:** Una tabla con comunidades, keywords, seminales, y tensiones. - -Para cada comunidad en la red de acoplamiento (la principal): - -1. **Nombre:** 1–3 palabras que capturen el enfoque (ej. "Métodos probabilísticos"). -2. **Keywords:** 5–7 palabras clave dominantes en esa comunidad. -3. **Seminales:** Top 2–3 papers (mayor grado) dentro de la comunidad. -4. **Descripción:** 2–3 frases de qué hacen esos papers. -5. **Tensión:** ¿Qué los diferencia de otras comunidades? ¿Dónde discrepan? - -### Con Claude - -```text -Para la red de acoplamiento, analizá cada comunidad: - -1. Nombre (síntesis del enfoque en 1–3 palabras) -2. Keywords principales (5–7 terms que definen esa comunidad) -3. Seminales: top 2 papers (por grado), con título, autores, año -4. Descripción: ¿qué hacen esos papers? ¿Cuál es el enfoque común? -5. Tensión: ¿en qué difieren de otras comunidades? - -Armame una tabla: [Comunidad | Enfoque | Keywords | Seminales | Tensión] -``` - -### Ejemplo de salida - -| Comunidad | Enfoque | Keywords | Seminales | Tensión | -|-----------|---------|----------|-----------|---------| -| **Probabilístico** | Modelos estadísticos, HMM | language model, smoothing, EM | [Smith 2008], [Brown 2010] | Eficiencia vs. cobertura | -| **Vectorial** | Embeddings, semántica latente | word embeddings, LSA, similarity | [Mikolov 2013], [Pennington 2014] | Interpretabilidad vs. performance | -| **Neuronal** | Deep learning, transformers | neural networks, attention, BERT | [Vaswani 2017], [Devlin 2019] | Costo computacional vs. generalización | - ---- - -## Paso 8 — Analiza tendencias e influencias - -**Entrada:** Redes, comunidades, corpus. -**Salida:** Observaciones sobre evolución, actores clave, huecos. - -Responde estas preguntas: - -### 1. ¿Cómo evolucionó el campo? - -```text -Muestra: -- Gráfico de # papers/año en el corpus -- Cómo cambiaron las comunidades (% de papers) año a año -- ¿Hay una comunidad que crecía y ahora decrece? -- ¿Hay una emergente (crecimiento exponencial últimos 3 años)? -``` - -### 2. ¿Quiénes son los influyentes? - -```text -Top 10 autores por: -- Cantidad de papers (productividad) -- Grado en la red de co-citación (influencia) -- Betweenness (actúan de "puente" entre comunidades) -``` - -### 3. ¿Dónde están los huecos? - -```text -Mirando las 3 redes, identificá: -- Comunidades o autores que no se conectan entre sí (fronteras vacías) -- Combinaciones de keywords que NO aparecen (gaps) -- Preguntas que nadie se hace (inferir de lo que sí hay) -``` - -### 4. ¿Quién lidera por institución? - -```text -Co-autoría: top 10 instituciones por: -- Cantidad de papers -- Colaboraciones externas -``` - ---- - -## Paso 9 — Redactá el reporte - -**Entrada:** Análisis anterior, comunidades, tendencias. -**Salida:** Documento estructurado (Markdown, Word, Google Docs). - -### Estructura recomendada - -``` -RESUMEN EJECUTIVO -├─ Pregunta de investigación -├─ Hallazgos principales (2–3 frases) -└─ Síntesis de una línea - -INTRODUCCIÓN -├─ Contexto y motivación -├─ Pregunta de investigación -└─ Scope - -METODOLOGÍA -├─ Ecuación de búsqueda -├─ Criterios PRISMA (en una frase) -├─ Tamaño final: X papers, años A–B -└─ Redes construidas (acoplamiento, co-citación, co-autoría) - -MAPEO DEL CAMPO -├─ Tabla de comunidades (visto en Paso 7) -├─ Figura: red de acoplamiento coloreada -├─ Trabajos seminales por comunidad -└─ Descripción de cada enfoque (prosa) - -TENDENCIAS Y EVOLUCIÓN -├─ Trayectoria temporal -├─ Shift de enfoques (cuál sube, cuál baja) -├─ Emergentes (keywords nuevas, comunidades nuevas) -└─ Actores clave (top autores, instituciones) - -TENSIONES Y DEBATES -├─ Matriz: Enfoque A vs. Enfoque B, qué diferencia -├─ Dónde se superponen, dónde divergen -├─ Huecos de investigación -└─ Preguntas abiertas - -CONCLUSIONES -├─ Síntesis de hallazgos -├─ Implicaciones para investigación futura -└─ Recomendaciones - -APÉNDICES -├─ Tabla: todos los papers (corpus completo) -├─ CSV de papers → comunidad -└─ GraphML (red para abrir en Gephi/Cytoscape) -``` - -### Herramientas de escritura - -- **Google Docs:** Colaboración y comentarios; exportás a .docx después. -- **Markdown + Pandoc:** Máximo control; exportás a PDF/DOCX/HTML. -- **Obsidian:** Integración con Zotero; bueno para notas de investigación. -- **Quarto/Jupyter:** Si querés reproducibilidad y código integrado. - -### Tips de redacción - -- **Cada comunidad merece un párrafo.** No amontonés. -- **Las figuras llevan leyendas explicativas.** "Red de acoplamiento bibliográfico - con N nodos (papers), M aristas (referencias compartidas), K comunidades - (detectadas por Louvain, resolution=1.0). Cada color = una comunidad. - Los nodos más grandes = papers de mayor grado (más referencias compartidas)." -- **Tensiones no son "problemas abiertos".** Son donde dos enfoques dicen cosas - diferentes. Ej. "La escuela probabilística prioriza eficiencia computacional, - mientras que la neuronal prioriza generación de resultados. En corpus multilingües, - esto afecta cómo se mapean traducciones." - ---- - -## Paso 10 — Versiona tu trabajo - -**Entrada:** Reporte, corpus, redes. -**Salida:** Carpeta reproducible. - -### Si usaste Claude web - -Descarga: - -- `corpus.parquet` — tu semilla guardada (subirla a Claude luego para continuar). -- `*.graphml` — networks para Gephi/Cytoscape. -- `clusters.csv` — papers → comunidad. -- `reporte.docx` o `reporte.md` — tu análisis final. - -Guardalos en una carpeta: `sota-[tema]-[fecha]/` - -### Si usaste bib2graph localmente - -El corpus vive en `.duckdb`; las redes se exportan automáticamente: - -```bash -# Exportá todo -b2g export --format graphml -b2g export --format csv - -# Versioná -git add . -git commit -m "SOTA: [Tu Tema] — corpus, redes, reporte" -``` - ---- - -## Checklist final - -- [ ] Pregunta de investigación clara y formulada -- [ ] Ecuación de búsqueda documentada y testeada -- [ ] Corpus de 100–300 papers ACCEPTED (curados por PRISMA) -- [ ] 3 redes construidas y visualizadas -- [ ] Comunidades nombradas, con keywords, seminales y tensiones identificadas -- [ ] Tendencias temporales e influencias (autores, instituciones) documentadas -- [ ] Huecos y fronteras vacías identificados -- [ ] Reporte redactado con estructura clara y figuras con leyendas -- [ ] Artefactos (GraphML, CSV, corpus) guardados y versionados -- [ ] ¿Se puede reproducir desde la ecuación de búsqueda? ✓ - ---- - -## Siguientes pasos - -- **Análisis más profundo:** Elige una comunidad y haz un sub-SOTA acotado. -- **Integración con tu investigación:** Posicioná tu trabajo en el mapa — ¿dónde - caés? ¿Dónde resolvés una tensión? -- **Publicación:** Convertí el SOTA en un paper, capítulo de tesis, o entrada de - blog. - ---- - -## Referencias - -- [Guías (how-to)](../guias/index.md) — recetas acotadas que complementan cada - paso: ecuación, forrajeo, curación PRISMA, lectura de redes y redacción del reporte. -- [Arquitectura de bib2graph](../ARCHITECTURE.md) -- [Referencia del CLI `b2g`](../reference/cli.md) -- [API Python](../reference/python-api.md) diff --git a/mkdocs.yml b/mkdocs.yml index 8283735..008ccc5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -126,17 +126,17 @@ exclude_docs: | ROADMAP/ RELEASE_TEMPLATE.md -# Estructura Diátaxis (https://diataxis.fr): Empezar/Tutoriales (aprender), -# Guías (resolver una tarea), Referencia (consultar), Explicación (entender). +# Estructura Diátaxis (https://diataxis.fr): Inicio (aprender/empezar, camino +# recomendado = asistente de IA — incluye el único tutorial), Guías (resolver +# una tarea), Referencia (consultar). La Explicación (entender: arquitectura, +# ADRs, PRD) vive dentro de "Contribuye" — es contexto para quien va a tocar +# el código, no una sección aparte. nav: - - Inicio: index.md - - Empezar: + - Inicio: + - index.md - Instalación: getting-started/installation.md - Quickstart: getting-started/quickstart.md - - Tutoriales: - - tutoriales/index.md - - Tu primer mapa (5 min): tutoriales/claude-code.md - - De la pregunta al reporte de SOTA: tutoriales/sota-completo.md + - Tu primer mapa (5 min): tutoriales/primer-mapa.md - Guías (how-to): - guias/index.md - Ecuación de búsqueda: guias/ecuacion-busqueda.md @@ -148,13 +148,11 @@ nav: - API de Python: reference/python-api.md - CLI b2g: reference/cli.md - Glosario: reference/glosario.md - - Contratos detallados: API.md - - Explicación: + - Contribuye: + - Contribuir: contributing.md - Arquitectura: ARCHITECTURE.md - Decisiones de diseño (ADRs): decisiones/README.md - Requisitos del producto (PRD): PRD.md - - Proyecto: - - Contribuir: contributing.md - Versionado: versioning.md - IA en el desarrollo: ai-disclosure.md - Changelog: changelog.md From b5cc25e0703a48fd24cc1b16c3b635642da6a488 Mon Sep 17 00:00:00 2001 From: complexluise Date: Thu, 2 Jul 2026 13:15:50 -0500 Subject: [PATCH 4/4] =?UTF-8?q?docs(mkdocs):=20limpiar=20enlaces=20rotos?= =?UTF-8?q?=20del=20sitio=20(87=E2=86=9210=20warnings)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - mkdocs.yml: mantiene ADRs como not_in_nav (transferencia, sin sidebar). - 28 docs: enlaces a Notas/exploracion/ROADMAP se preservan como texto, sin sintaxis de link (la prosa sigue citando la fuente). Esto incluye 24 ADRs (inmutables en contenido narrativo, sí modificados en formato de un enlace para que mkdocs no proteste). - 10 warnings restantes son falsos positivos del patron include-markdown (changelog/contributing/ai-disclosure heredan enlaces VERSIONING/CONTRIBUTING/AGENTS de archivos de raiz). Son funcionales en GitHub; dejados pasar por diseno del PO. Sitio compila en 0 errores. Build limpio con exit 0. --- docs/API.md | 2 +- docs/ARCHITECTURE.md | 6 +++--- docs/PRD.md | 18 +++++++++--------- .../0006-tabla-canonica-y-networkspec.md | 2 +- docs/decisiones/0007-openalex-backbone.md | 2 +- docs/decisiones/0008-wedge-forrajeo.md | 8 ++++---- docs/decisiones/0010-agente-native-columna.md | 2 +- docs/decisiones/0011-thesaurus-multilingue.md | 2 +- docs/decisiones/0012-openalex-credenciales.md | 2 +- docs/decisiones/0015-corpus-tabular-backend.md | 2 +- docs/decisiones/0016-maquina-estados-lazo.md | 8 ++++---- .../0017-reproducibilidad-historia-snapshot.md | 2 +- ...020-metodo-forrajeo-scent-filtros-reject.md | 8 ++++---- .../0022-producto-sin-ia-generativa.md | 14 +++++++------- .../0023-capa-constants-modelos-schema.md | 4 ++-- .../0024-orden-d3-columna-secuencia-duckdb.md | 2 +- .../0025-enricher-cocitacion-openalex.md | 6 +++--- .../0026-dedup-fuzzy-determinista.md | 2 +- .../0027-pivote-posicionamiento-gui-local.md | 4 ++-- ...0028-arquitectura-gui-api-capa-servicios.md | 2 +- ...0030-ecuacion-declarativa-corpus-ejemplo.md | 4 ++-- .../0032-capa-servicios-duena-del-flujo.md | 2 +- ...roducto-library-centric-grafo-proyeccion.md | 4 ++-- .../0034-etiquetado-tabla-tags-lateral.md | 4 ++-- .../0035-ingesta-multipuerta-resolucion-doi.md | 4 ++-- .../0037-superficie-cli-10-verbos-ciclo.md | 6 +++--- docs/decisiones/README.md | 12 ++++++------ docs/decisiones/registro-ia.md | 12 ++++++------ mkdocs.yml | 5 +++-- 29 files changed, 76 insertions(+), 75 deletions(-) diff --git a/docs/API.md b/docs/API.md index c5f3887..72fcd32 100644 --- a/docs/API.md +++ b/docs/API.md @@ -3,7 +3,7 @@ > Contratos de las costuras y del núcleo: el "producto" que ve quien la integra o la extiende. > Son **bocetos de interfaz** (firmas + docstrings), no la implementación: el código es la fuente de > verdad última y este doc describe el contrato que ese código cumple. Diseño de fondo en -> [`ARCHITECTURE.md`](ARCHITECTURE.md); método en [`Notas/metodología.md`](Notas/metodología.md). +> [`ARCHITECTURE.md`](ARCHITECTURE.md); método en `Notas/metodología.md`. > > El `Corpus` es una **tabla Arrow validada con Pydantic v2** (ADR > [0006](decisiones/0006-tabla-canonica-y-networkspec.md)) respaldada por un **`TabularBackend`** diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 92cfe26..69dbfe3 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -6,7 +6,7 @@ > bibliométrica determinista** (*information scent*), sin LLM ni embeddings. El desarrollo sí es > asistido por IA; el producto no. El "porqué" de cada decisión vive en los ADR de > [`decisiones/`](decisiones/) (linkeados en cada sección); el método en -> [`Notas/metodología.md`](Notas/metodología.md); los contratos públicos en [`API.md`](API.md). +> `Notas/metodología.md`; los contratos públicos en [`API.md`](API.md). ## 1. Idea en un párrafo @@ -130,7 +130,7 @@ Funciones puras sobre `networkx.Graph`: **métricas** (densidad, componentes, cl fuerte si falta—, propagación, modularidad voraz), **asortatividad** (por un **atributo categórico configurable** —p. ej. región— y por grado, más la **composición de cada comunidad**; las métricas sobre un **proxy** se reportan con su disclaimer; el atributo es config del usuario, no hardcodeado) e -**informe de calidad** de la co-citación ([`metodología.md`](Notas/metodología.md) §4, umbrales +**informe de calidad** de la co-citación (`metodología.md` §4, umbrales configurables). ### 3.4 `Exporter` — resultados → archivos @@ -248,7 +248,7 @@ expone `CycleState` (`SEEDED/FORAGED/FILTERED/BUILT/MONITORED`), `apply_transiti round) → (state, round)`, `available_transitions(state)` y `CURATION_ACTIONS`. El backend persiste el estado y la **ronda** en `loop_state_log`. -FSM **cíclico** fiel a la [Nota 05](Notas/05-ciclo-investigacion-humano.md): +FSM **cíclico** fiel a la Nota 05: ``` SEEDED ──chain──► FORAGED ──filter──► FILTERED ──build──► BUILT ──monitor──► MONITORED diff --git a/docs/PRD.md b/docs/PRD.md index 8253641..3a91bcc 100644 --- a/docs/PRD.md +++ b/docs/PRD.md @@ -6,7 +6,7 @@ > [0022](decisiones/0022-producto-sin-ia-generativa.md)): la asistencia del forrajeo es estructura > bibliométrica determinista (*information scent*); el desarrollo sí es asistido por IA. Diseño en > [`ARCHITECTURE.md`](ARCHITECTURE.md); contratos en [`API.md`](API.md); método en -> [`Notas/metodología.md`](Notas/metodología.md). +> `Notas/metodología.md`. ## 1. Qué es @@ -39,8 +39,8 @@ que **la colección vive** (berry growing).* ## 2. Problema que resuelve La exploración bibliográfica humana es **iterativa, no lineal** (Kuhlthau, Ellis, Bates, -Pirolli, Wohlin — ver [`Notas/05`](Notas/05-ciclo-investigacion-humano.md) y -[`metodología.md`](Notas/metodología.md)): se siembra, se hace *chaining*, la query y la idea +Pirolli, Wohlin — ver `Notas/05` y +`metodología.md`): se siembra, se hace *chaining*, la query y la idea **mutan** al leer (berrypicking), y la colección **se cultiva** en el tiempo (berry growing). El snowballing manual es mecánico y agota; documentarlo con rigor (PRISMA / vom Brocke) es trabajo. @@ -57,7 +57,7 @@ Falta una herramienta **abierta, poseída por el investigador**, que parta de la consciente**, **asista el forrajeo** usando la estructura bibliométrica como *information scent*, y conserve una **biblioteca viva reproducible**. -La contribución (y la tesis del paper, [`Notas/05`](Notas/05-ciclo-investigacion-humano.md) §5) +La contribución (y la tesis del paper, `Notas/05` §5) es **re-instrumentar el ciclo humano clásico** con un método donde la **estructura bibliométrica funciona como *information scent*** (forrajeo asistido, **determinista y reproducible, sin IA generativa**), **sin desplazar el juicio humano**. Mapeo del ciclo de 9 pasos (05 §3–4) sobre el @@ -215,7 +215,7 @@ viva. La experiencia visual library-centric vive en un **producto separado**, fu bibliométrico** del forrajeo (acoplamiento/co-citación/centralidad, determinista, reproducible). El **juicio humano** (formular la idea, dejarla mutar, decidir qué curar, leer las tensiones) **no se automatiza**. "AI-in-the-loop" se refiere **solo** al *desarrollo* asistido por IA (ver - [`AI_DISCLOSURE.md`](../AI_DISCLOSURE.md)). + `AI_DISCLOSURE.md`). 3. **Núcleo puro, costuras opcionales.** La lógica bibliométrica no depende de servidores ni red. 4. **Configuración inyectada, nunca embebida.** Ningún secreto en el código, sin efectos de import. 5. **Contratos estables y tipados** entre costuras (sin *signature drift*). @@ -310,8 +310,8 @@ Detalle del schema de columnas + la API del wrapper en [`API.md`](API.md) §1. El caso de referencia de bib2graph es **el ciclo de investigación aplicado a la teoría que mejora bib2graph**: la herramienta **se usa a sí misma como objeto de estudio** para iterar su propio diseño. La literatura sobre **forrajeo de información, ciclo de investigación humano y bibliometría** (Bates, -Ellis, Kuhlthau, Pirolli, Wohlin, vom Brocke; ver [`Notas/05`](Notas/05-ciclo-investigacion-humano.md) -y [`metodología.md`](Notas/metodología.md)) es a la vez **el corpus que bib2graph procesa** y **la +Ellis, Kuhlthau, Pirolli, Wohlin, vom Brocke; ver `Notas/05` +y `metodología.md`) es a la vez **el corpus que bib2graph procesa** y **la fuente de los requisitos** del producto: sembrar la ecuación de esa teoría, forrajear sus referencias y citantes, curar la biblioteca viva, proyectar las redes y leer las tensiones es **lo que valida que el método sirve** — y cada vuelta del ciclo retroalimenta el diseño (qué falta en el forrajeo, qué red @@ -324,7 +324,7 @@ vivos** reflejan el resultado, no el debate. El caso **intercambio ecológico desigual (IED)** —el pipeline corrido end-to-end sobre papers reales de OpenAlex, con redes con estructura, thesaurus multilingüe y asimetría Norte–Sur medible (ver -[`exploracion/informe_ied_lectura_2.md`](../exploracion/informe_ied_lectura_2.md))— queda como **caso +`exploracion/informe_ied_lectura_2.md`)— queda como **caso de validación interna histórico**: evidencia de que el método produce resultados con datos reales, **no un criterio de release**. El estudio de semiconductores sigue como caso documentado en -[`metodología.md`](Notas/metodología.md). +`metodología.md`. diff --git a/docs/decisiones/0006-tabla-canonica-y-networkspec.md b/docs/decisiones/0006-tabla-canonica-y-networkspec.md index 43a5891..4d99d28 100644 --- a/docs/decisiones/0006-tabla-canonica-y-networkspec.md +++ b/docs/decisiones/0006-tabla-canonica-y-networkspec.md @@ -45,7 +45,7 @@ que aparecieron al planificar la implementación: sin reinventar un formato. Una exploración más amplia (cuatro arquitecturas candidatas) está en -[`exploracion/arquitecturas-alternativas.md`](../Notas/02-exploracion/arquitecturas-alternativas.md). +`exploracion/arquitecturas-alternativas.md`. Las alternativas evaluadas y descartadas: - **Event sourcing / log inmutable:** sobreingeniería; el mismo poder se diff --git a/docs/decisiones/0007-openalex-backbone.md b/docs/decisiones/0007-openalex-backbone.md index 5e68965..e66f8c8 100644 --- a/docs/decisiones/0007-openalex-backbone.md +++ b/docs/decisiones/0007-openalex-backbone.md @@ -8,7 +8,7 @@ ## Contexto El diseño previo (ver [`../PRD.md`](../PRD.md) anterior y -[`../critica-base.md`](../Notas/critica-base.md) §1) pivoteaba sobre **BibTeX como entrada de +`../critica-base.md` §1) pivoteaba sobre **BibTeX como entrada de referencia**. Pero el BibTeX **no trae las listas de referencias citadas**, y eso fabricaba el problema más caro de toda la arquitectura: un `Enricher` de Semantic Scholar **estructural** para poder construir la red de co-citación (API keys, rate limits, rama opcional, reintentos diff --git a/docs/decisiones/0008-wedge-forrajeo.md b/docs/decisiones/0008-wedge-forrajeo.md index 45c55a3..e7da323 100644 --- a/docs/decisiones/0008-wedge-forrajeo.md +++ b/docs/decisiones/0008-wedge-forrajeo.md @@ -4,8 +4,8 @@ retira del producto; el forrajeo se asiste por estructura bibliométrica, sin IA — ver "Enmienda") - **Fecha:** 2026-06-15 - **Relacionada con:** [0007](0007-openalex-backbone.md), - [`../Notas/04-direccion-ia-in-the-loop.md`](../Notas/04-direccion-ia-in-the-loop.md), - [`../Notas/05-ciclo-investigacion-humano.md`](../Notas/05-ciclo-investigacion-humano.md) + `../Notas/04-direccion-ia-in-the-loop.md`, + `../Notas/05-ciclo-investigacion-humano.md` ## Contexto @@ -28,7 +28,7 @@ tensiones se difiere explícitamente a v2**. Los pasos 5 (organizar en evidencia ## Consecuencias - **Wedge entregable y ya validado**: el sandbox de intercambio ecológico desigual - ([`../exploracion/informe_ied_lectura_2.md`](../../exploracion/informe_ied_lectura_2.md)) corre + (`../exploracion/informe_ied_lectura_2.md`) corre este flujo end-to-end con datos reales de OpenAlex. - La **diferenciación de la V1** descansa en: ecuación consciente + reporte de traducción, biblioteca viva curada, ranking por estructura bibliométrica y CLI agente-native — **no** en @@ -42,7 +42,7 @@ tensiones se difiere explícitamente a v2**. Los pasos 5 (organizar en evidencia ## Enmienda — 2026-06-15 (la máquina de tensiones se retira del producto; el forrajeo no usa IA) > Motivada por el red-team del AS-BUILT v0.2 -> ([Nota 06](../Notas/06-critica-as-built-v0.2.md), RAÍZ 1) y la decisión del PO de que **el producto +> (Nota 06, RAÍZ 1) y la decisión del PO de que **el producto > no usa IA generativa** (ADR [0022](0022-producto-sin-ia-generativa.md)). El cuerpo del ADR (arriba) > queda como historia; esta enmienda corrige dos cosas. diff --git a/docs/decisiones/0010-agente-native-columna.md b/docs/decisiones/0010-agente-native-columna.md index e3e11d8..a9b770a 100644 --- a/docs/decisiones/0010-agente-native-columna.md +++ b/docs/decisiones/0010-agente-native-columna.md @@ -3,7 +3,7 @@ - **Estado:** Aceptada - **Fecha:** 2026-06-15 - **Relacionada con:** [0006](0006-tabla-canonica-y-networkspec.md) (§ CLI como API), - [`../critica-base.md`](../Notas/critica-base.md) §6 + `../critica-base.md` §6 ## Contexto diff --git a/docs/decisiones/0011-thesaurus-multilingue.md b/docs/decisiones/0011-thesaurus-multilingue.md index 3b11321..090abdb 100644 --- a/docs/decisiones/0011-thesaurus-multilingue.md +++ b/docs/decisiones/0011-thesaurus-multilingue.md @@ -5,7 +5,7 @@ - **Fecha:** 2026-06-15 - **Relacionada con:** [0006](0006-tabla-canonica-y-networkspec.md) (`Preprocessor`), [0007](0007-openalex-backbone.md) -- **Validado en:** [`../exploracion/informe_ied_lectura_2.md`](../../exploracion/informe_ied_lectura_2.md) +- **Validado en:** `../exploracion/informe_ied_lectura_2.md` (T6 y T10) ## Contexto diff --git a/docs/decisiones/0012-openalex-credenciales.md b/docs/decisiones/0012-openalex-credenciales.md index bde4b7a..0c749fd 100644 --- a/docs/decisiones/0012-openalex-credenciales.md +++ b/docs/decisiones/0012-openalex-credenciales.md @@ -7,7 +7,7 @@ (ver [`registro-ia.md`](registro-ia.md)) - **Relacionada con:** [0007](0007-openalex-backbone.md) (OpenAlex backbone), [0010](0010-agente-native-columna.md) (config inyectada); lecciones 1 y 6 de v0 -- **Observado en:** [`../../exploracion/scripts/01_search_openalex.py`](../../exploracion/scripts/01_search_openalex.py) +- **Observado en:** `../../exploracion/scripts/01_search_openalex.py` ## Contexto diff --git a/docs/decisiones/0015-corpus-tabular-backend.md b/docs/decisiones/0015-corpus-tabular-backend.md index 800dda2..bc31d69 100644 --- a/docs/decisiones/0015-corpus-tabular-backend.md +++ b/docs/decisiones/0015-corpus-tabular-backend.md @@ -74,7 +74,7 @@ estable entre la biblioteca viva (cualquier backend) y el núcleo puro de proyec `merge` (D3). El `corpus_hash` se computa siempre sobre el contenido (vía `to_arrow()`), nunca sobre detalles del backend. - **Costo (rework del Hito 1).** Hay que migrar `src/bib2graph/corpus.py`. Detalle accionable - para el `coder` en el milestone "Hito 1.5 — Rework de `Corpus`" del [ROADMAP](../ROADMAP/README.md); + para el `coder` en el milestone "Hito 1.5 — Rework de `Corpus`" del ROADMAP; resumen: - Extraer un `TabularBackend` (Protocol) en `src/bib2graph/backends/` (o módulo nuevo). Operaciones mínimas: `add_paper`, `merge`, `set_curation`/`apply_curation`, diff --git a/docs/decisiones/0016-maquina-estados-lazo.md b/docs/decisiones/0016-maquina-estados-lazo.md index 896526a..9c5f417 100644 --- a/docs/decisiones/0016-maquina-estados-lazo.md +++ b/docs/decisiones/0016-maquina-estados-lazo.md @@ -6,7 +6,7 @@ - **Relacionada con:** [0008](0008-wedge-forrajeo.md) (wedge = forrajeo), [0009](0009-biblioteca-viva-duckdb.md) (biblioteca viva en DuckDB), [0015](0015-corpus-tabular-backend.md) (`Corpus` sobre `TabularBackend`), - [`../Notas/05-ciclo-investigacion-humano.md`](../Notas/05-ciclo-investigacion-humano.md) + `../Notas/05-ciclo-investigacion-humano.md` ## Contexto @@ -60,7 +60,7 @@ los estados no son una escalera de un solo sentido. Bates/Ellis/Kuhlthau, al costo de que el `LoopState` es un **mapa**, no un guardia. - **Recomendación para el `coder`:** el `LoopState` (enum + transición + timestamp) y la tabla que lo persiste caen en el **Hito 3** (`DuckDBBackend`/`DuckDBStore`); el comando `b2g status` en el - **Hito 6** (CLI). Ver [ROADMAP](../ROADMAP/README.md) Hitos 3 y 6. + **Hito 6** (CLI). Ver ROADMAP Hitos 3 y 6. - **Tensión declarada:** la máquina de estados es del **archivo vivo**; el **snapshot** (ADR [0017](0017-reproducibilidad-historia-snapshot.md)) es una foto que puede incluir el `LoopState` del instante sellado, pero no es donde vive. @@ -68,7 +68,7 @@ los estados no son una escalera de un solo sentido. ## Enmienda — 2026-06-15 (FSM cíclico de dominio; `reseed` de primera clase; curación transversal) > Motivada por el red-team del AS-BUILT v0.2 -> ([Nota 06](../Notas/06-critica-as-built-v0.2.md), RAÍZ 1): este ADR prometía no-linealidad de +> (Nota 06, RAÍZ 1): este ADR prometía no-linealidad de > primera clase, pero el AS-BUILT la entregó como un enum **lineal** (`SEEDED→FORAGED→FILTERED→BUILT`) > enterrado en `backends/duckdb.py:67-78`, con la no-linealidad reducida a un comentario > ("transiciones permisivas") y la curación **invisible** en el mapa. El cuerpo del ADR (arriba) @@ -77,7 +77,7 @@ los estados no son una escalera de un solo sentido. 1. **El ciclo es un concepto de DOMINIO puro y testeable** — módulo nuevo `cycle.py` (núcleo): el modelo de estados + las reglas de transición viven ahí; el **backend solo lo persiste** (el `LoopState` deja de estar definido dentro de `backends/duckdb.py`). -2. **FSM cíclico fiel a la [Nota 05](../Notas/05-ciclo-investigacion-humano.md):** +2. **FSM cíclico fiel a la Nota 05:** ``` SEEDED ─(chain)→ FORAGED ─(filter)→ FILTERED ─(build)→ BUILT ─(monitor)→ MONITORED diff --git a/docs/decisiones/0017-reproducibilidad-historia-snapshot.md b/docs/decisiones/0017-reproducibilidad-historia-snapshot.md index 7a43639..b21da31 100644 --- a/docs/decisiones/0017-reproducibilidad-historia-snapshot.md +++ b/docs/decisiones/0017-reproducibilidad-historia-snapshot.md @@ -63,7 +63,7 @@ en fechas distintas no son comparables. ## Enmienda — 2026-06-15 (identidad vs procedencia; reloj en la frontera; Louvain seeded) > Motivada por el red-team del AS-BUILT v0.2 -> ([Nota 06](../Notas/06-critica-as-built-v0.2.md), RAÍZ 2): el **principio de este ADR es +> (Nota 06, RAÍZ 2): el **principio de este ADR es > correcto**, pero el **código no lo cumple** — el `corpus_hash` actual **incluye los timestamps de > curación**, así que dos corridas que aceptan los mismos ids producen hash distinto y el snapshot > **no** es reproducible bit a bit. El cuerpo del ADR (arriba) queda como historia; esta enmienda diff --git a/docs/decisiones/0020-metodo-forrajeo-scent-filtros-reject.md b/docs/decisiones/0020-metodo-forrajeo-scent-filtros-reject.md index b831d44..4e3aba0 100644 --- a/docs/decisiones/0020-metodo-forrajeo-scent-filtros-reject.md +++ b/docs/decisiones/0020-metodo-forrajeo-scent-filtros-reject.md @@ -124,7 +124,7 @@ decía que `keywords_id` son los "canónicos (post-thesaurus)": antes de aplicar ## Enmienda — 2026-06-15 (scent bibliométrico determinista; sin LLM) > Motivada por el red-team del AS-BUILT v0.2 -> ([Nota 06](../Notas/06-critica-as-built-v0.2.md), RAÍZ 1) y la decisión del PO de que **el producto +> (Nota 06, RAÍZ 1) y la decisión del PO de que **el producto > no usa IA generativa** (ADR [0022](0022-producto-sin-ia-generativa.md)). El cuerpo del ADR (arriba) > queda como historia; esta enmienda revierte la decisión **A** (scent = frecuencia de enlace) y > elimina el stub LLM. @@ -132,7 +132,7 @@ decía que `keywords_id` son los "canónicos (post-thesaurus)": antes de aplicar 1. **El scent pasa de "frecuencia de enlace" a estructura bibliométrica.** El *information scent* usa los **PROYECTORES** —**acoplamiento / co-citación / centralidad** del candidato respecto del corpus curado— en vez del conteo aritmético de citas directas. Es lo que la - [Nota 05](../Notas/05-ciclo-investigacion-humano.md) §4 siempre prometió ("la bibliometría ES el + Nota 05 §4 siempre prometió ("la bibliometría ES el information scent… mapea a los proyectores"). Sigue siendo una **función pura y determinista** (mismo corpus → mismo ranking, mismo desempate por `id`), **sin LLM ni embeddings**. El forrajeo (costura) **depende del núcleo de proyección** (puro); el núcleo nunca de la costura. @@ -289,8 +289,8 @@ semántica. ### El "no contaminan" era falso — los stubs SÍ contaminaron -Las sesiones de QA con datos reales lo destaparon ([Nota 09](../Notas/09-sesion-qa-prueba-ecologia-valoraciones.md), -[Nota 13](../Notas/13-continuacion-sesion-valoraciones.md), "el bug de fondo del Forager"): los stubs +Las sesiones de QA con datos reales lo destaparon (Nota 09, +Nota 13, "el bug de fondo del Forager"): los stubs `[candidate:W...]` **sí contaminaron**. Llegaron a ser **~la mitad del corpus** (filas-fantasma sin metadata real) y, peor, **entraron al `corpus_hash`** (eran filas del `corpus`, no ruido externo) — rompiendo la reproducibilidad y las redes legibles. La promesa de "curables/enriquecibles después" diff --git a/docs/decisiones/0022-producto-sin-ia-generativa.md b/docs/decisiones/0022-producto-sin-ia-generativa.md index 48274f0..caf3367 100644 --- a/docs/decisiones/0022-producto-sin-ia-generativa.md +++ b/docs/decisiones/0022-producto-sin-ia-generativa.md @@ -3,19 +3,19 @@ - **Estado:** Aceptada - **Fecha:** 2026-06-15 - **Decidido por:** Product Owner humano (tras el red-team de la - [`../Notas/06-critica-as-built-v0.2.md`](../Notas/06-critica-as-built-v0.2.md)) + `../Notas/06-critica-as-built-v0.2.md`) - **Relacionada con:** [0008](0008-wedge-forrajeo.md) (wedge = forrajeo; tensiones removidas), [0011](0011-thesaurus-multilingue.md) (thesaurus determinista, sin fallback LLM), [0020](0020-metodo-forrajeo-scent-filtros-reject.md) (scent = estructura bibliométrica), - [`../Notas/04-direccion-ia-in-the-loop.md`](../Notas/04-direccion-ia-in-the-loop.md) (base de la + `../Notas/04-direccion-ia-in-the-loop.md` (base de la "máquina de tensiones", ahora abandonada), - [`../Notas/05-ciclo-investigacion-humano.md`](../Notas/05-ciclo-investigacion-humano.md) + `../Notas/05-ciclo-investigacion-humano.md` ## Contexto El giro "IA in the loop" (Notas 04/05) proponía **dos puntos de inserción de IA** en el producto: nº1 (forrajeo) y nº2 (sensemaking / "máquina de tensiones"). El red-team del AS-BUILT v0.2 -([Nota 06](../Notas/06-critica-as-built-v0.2.md), RAÍZ 1) mostró que esa IA-en-el-producto es **casi +(Nota 06, RAÍZ 1) mostró que esa IA-en-el-producto es **casi vapor**: el forrajeo rankea por un **conteo aritmético** (no bibliometría, no IA), la curación es **100% humana**, y el único gancho de LLM (`explain_candidate`) es un `NotImplementedError` permanente con el extra `[llm]` vacío. README/AI_DISCLOSURE/Nota 05, en cambio, **venden IA en el @@ -39,7 +39,7 @@ bibliométrica como *information scent***, **determinista y reproducible** (acop [0008](0008-wedge-forrajeo.md) actualizado). El **sensemaking sigue siendo humano**, asistido por las redes (no por IA). 3. **Queda un solo sentido de "AI-in-the-loop":** el *desarrollo* de la librería es asistido por IA - (ver [`../../AI_DISCLOSURE.md`](../../AI_DISCLOSURE.md)); el *producto* **no** usa IA. Ya no hay + (ver `../../AI_DISCLOSURE.md`); el *producto* **no** usa IA. Ya no hay "dos inserciones de IA": hay **una inserción algorítmica** (forrajeo por estructura bibliométrica), que no es IA. @@ -75,7 +75,7 @@ centralidad diferida) se documentan en el AS-BUILT del ADR ## Enmienda — 2026-06-17 (la curación automatizada `[auto-vN]` es opt-in y excepción, NO default · #65) -La [Nota 13](../Notas/13-continuacion-sesion-valoraciones.md) (sesión de QA con el caso +La Nota 13 (sesión de QA con el caso `valoraciones`) usó **curación automatizada por heurísticas de keywords** sobre título/abstract/keywords para cerrar el ciclo de QA sin esperar la CLI de curación (#22/#26). Cada decisión del clasificador quedó marcada con un tag de auditoría (`[auto-v1]`/`[auto-v3]`/ @@ -94,5 +94,5 @@ Esto **NO modifica la decisión de este ADR.** La regla **"la curación es 100% auditoría + reversibilidad humana); el humano sigue siendo quien acepta o revierte. Esa sería una **decisión nueva** (enmienda o ADR nuevo), no un comportamiento por defecto. -Referencia: [Nota 13 — Continuación de la sesión QA](../Notas/13-continuacion-sesion-valoraciones.md) +Referencia: Nota 13 — Continuación de la sesión QA §"La excepción a la regla 'curación 100% humana'". diff --git a/docs/decisiones/0023-capa-constants-modelos-schema.md b/docs/decisiones/0023-capa-constants-modelos-schema.md index 5c19acd..3cfb6dc 100644 --- a/docs/decisiones/0023-capa-constants-modelos-schema.md +++ b/docs/decisiones/0023-capa-constants-modelos-schema.md @@ -3,7 +3,7 @@ - **Estado:** Aceptada - **Fecha:** 2026-06-15 - **Decidido por:** Product Owner humano (tras el red-team de la - [`../Notas/06-critica-as-built-v0.2.md`](../Notas/06-critica-as-built-v0.2.md), secciones CONSTANTS + `../Notas/06-critica-as-built-v0.2.md`, secciones CONSTANTS y MODELS) - **Relacionada con:** [0006](0006-tabla-canonica-y-networkspec.md) (tabla canónica + schema Pydantic), [0013](0013-identidad-hash-merge-corpus.md) (`provenance` como log append-only), @@ -11,7 +11,7 @@ ## Contexto -El red-team del AS-BUILT v0.2 ([Nota 06](../Notas/06-critica-as-built-v0.2.md)) encontró dos clases +El red-team del AS-BUILT v0.2 (Nota 06) encontró dos clases de fragilidad de base: - **No hay módulo de constantes.** ~62 nombres de columna viven como **string-literal** en 14 diff --git a/docs/decisiones/0024-orden-d3-columna-secuencia-duckdb.md b/docs/decisiones/0024-orden-d3-columna-secuencia-duckdb.md index e453af3..4c79d2e 100644 --- a/docs/decisiones/0024-orden-d3-columna-secuencia-duckdb.md +++ b/docs/decisiones/0024-orden-d3-columna-secuencia-duckdb.md @@ -21,7 +21,7 @@ por fila** en cada `merge` (reescribía la tabla entera). La causa raíz: `_arro el orden de primera aparición. La única forma de garantizar D3 era reescribir físicamente toda la tabla en el orden correcto en cada `merge`. -La [Nota 06](../Notas/06-critica-as-built-v0.2.md) / el review marcaron ese **full-rewrite por +La Nota 06 / el review marcaron ese **full-rewrite por merge** como la única operación con olor a ineficiencia real (no un bug) del backend: en una **biblioteca viva** (ADR 0009) que mergea en **cada ronda de chaining/reseed**, reescribir toda la tabla por fila escala mal con el tamaño del corpus. diff --git a/docs/decisiones/0025-enricher-cocitacion-openalex.md b/docs/decisiones/0025-enricher-cocitacion-openalex.md index 36151c6..17a18fb 100644 --- a/docs/decisiones/0025-enricher-cocitacion-openalex.md +++ b/docs/decisiones/0025-enricher-cocitacion-openalex.md @@ -7,11 +7,11 @@ estructural y S2 se demota), [0004](0004-enriquecimiento-opcional.md) (principio de enriquecimiento opt-in, nunca obligatorio, keys inyectadas), [0014](0014-proyeccion-redes-pesos-asortatividad.md) (semántica del `CoCitationProjector`), [0021](0021-cli-agente-native-contrato.md) (set de - subcomandos del CLI), [`metodología.md`](../Notas/metodología.md) (co-citación = citantes compartidos) + subcomandos del CLI), `metodología.md` (co-citación = citantes compartidos) ## Contexto -El Hito 8 ([ROADMAP/04](../ROADMAP/04-lo-que-viene.md)) materializa la costura `Enricher` opt-in +El Hito 8 (ROADMAP/04) materializa la costura `Enricher` opt-in para resolver `references_id`→`references_doi` y habilitar la **co-citación** end-to-end. El DoD original del hito lo encuadraba sobre el extra **`[s2]`** (Semantic Scholar), residuo del diseño **pre-giro** previo al [ADR 0007](0007-openalex-backbone.md): cuando la entrada era BibTeX, el único @@ -78,7 +78,7 @@ El hito es grande para un solo ciclo, por lo que se **parte en dos**: El `CoCitationProjector` (ADR [0014](0014-proyeccion-redes-pesos-asortatividad.md)) **no se toca**: cuenta **`cited_by_id` compartido** = los **citantes compartidos** de la -[`metodología.md`](../Notas/metodología.md). La frase de los docs "citantes con sus citas" se **reconcilia** +`metodología.md`. La frase de los docs "citantes con sus citas" se **reconcilia** documentando que el 2º nivel se materializa como **`cited_by_id`** (8b): "citantes con sus citas" ≡ **`cited_by_id` compartido**, que es lo que el projector ya consume. diff --git a/docs/decisiones/0026-dedup-fuzzy-determinista.md b/docs/decisiones/0026-dedup-fuzzy-determinista.md index 87dc5b9..3ee9bc3 100644 --- a/docs/decisiones/0026-dedup-fuzzy-determinista.md +++ b/docs/decisiones/0026-dedup-fuzzy-determinista.md @@ -23,7 +23,7 @@ ## Contexto -El Hito 7 ([ROADMAP/04](../ROADMAP/04-lo-que-viene.md)) materializa la deduplicación **fuzzy** de +El Hito 7 (ROADMAP/04) materializa la deduplicación **fuzzy** de `authors_id` y `keywords_id`: el complemento aproximado de la normalización conservadora del `Preprocessor` (ADR 0011, Hito 5), que solo colapsa variantes triviales (lowercase, acentos, espacios) y matchea keywords contra el thesaurus curado. Lo que queda son variantes **casi-iguales** diff --git a/docs/decisiones/0027-pivote-posicionamiento-gui-local.md b/docs/decisiones/0027-pivote-posicionamiento-gui-local.md index b0f7dd6..3ed9729 100644 --- a/docs/decisiones/0027-pivote-posicionamiento-gui-local.md +++ b/docs/decisiones/0027-pivote-posicionamiento-gui-local.md @@ -13,8 +13,8 @@ [0021](0021-cli-agente-native-contrato.md) (contrato del CLI), [0029](0029-workspace-por-investigacion.md) (workspace = unidad de proyecto, prerequisito ya hecho). - **Epic:** GUI local [#34](https://github.com/complexluise/bib2graph/issues/34). Dirección en - Notas [07](../Notas/07-frontend-tool-for-thought.md)/[08](../Notas/08-referentes-frontend.md)/ - [10](../Notas/10-sintesis-contextualizacion-gui.md). + Notas 07/08/ + 10. ## Contexto diff --git a/docs/decisiones/0028-arquitectura-gui-api-capa-servicios.md b/docs/decisiones/0028-arquitectura-gui-api-capa-servicios.md index e00f4bb..ffff590 100644 --- a/docs/decisiones/0028-arquitectura-gui-api-capa-servicios.md +++ b/docs/decisiones/0028-arquitectura-gui-api-capa-servicios.md @@ -19,7 +19,7 @@ ## Contexto -La [Nota 12](../Notas/12-arquitectura-gui-encuadre.md) (revisada 2026-06-18) encuadró la arquitectura: +La Nota 12 (revisada 2026-06-18) encuadró la arquitectura: la GUI agrega un **4º frontend (SPA)** y una **costura nueva de servidor (API local)**, sin romper "núcleo puro + costuras". El principio es **no tener dos implementaciones de la lógica de negocio**: CLI y API deben compartir la orquestación. diff --git a/docs/decisiones/0030-ecuacion-declarativa-corpus-ejemplo.md b/docs/decisiones/0030-ecuacion-declarativa-corpus-ejemplo.md index 3acd8ed..241e364 100644 --- a/docs/decisiones/0030-ecuacion-declarativa-corpus-ejemplo.md +++ b/docs/decisiones/0030-ecuacion-declarativa-corpus-ejemplo.md @@ -22,7 +22,7 @@ `corpus_hash`), [0005](0005-dependencias-extras.md) (extra `[bibtex]` perezoso). - **Prerequisito de:** Ciclo #33 ("caso real reproducido") → **gate de #34** (epic GUI). - **Issues / contexto:** #14 (`--max-results`), #30 (`--exclude`), #25/#31 (redes legibles + - `clusters.csv`), #26 (`curate --from-csv`), [Nota 09](../Notas/09-sesion-qa-prueba-ecologia-valoraciones.md) + `clusters.csv`), #26 (`curate --from-csv`), Nota 09 (sesión QA — ecología de valoraciones; agujero R2 de reproducibilidad de comunidades). ## Contexto @@ -353,7 +353,7 @@ lo construido. **Gate verde, 571 tests; el verifier pasa.** **composición de comunidades es estable entre corridas** (Louvain seeded); redes no vacías (coupling 132/3897, author_collab 327/729, institution_collab 136/300, keyword 483/5350; co-citación vacía omitida graceful porque `cited_by_id` está en blanco). **Cierra el agujero R2 - que la [Nota 09](../Notas/09-sesion-qa-prueba-ecologia-valoraciones.md) dejó abierto** sobre la + que la Nota 09 dejó abierto** sobre la estabilidad de la composición de comunidades. - **Bifurcación residual del PO resuelta (opción mínima):** `examples/valoraciones/` commitea **solo el corpus + `equation.yaml` + README + script**, no un `workspace.json`/`library.duckdb` diff --git a/docs/decisiones/0032-capa-servicios-duena-del-flujo.md b/docs/decisiones/0032-capa-servicios-duena-del-flujo.md index 3433f92..deed6b3 100644 --- a/docs/decisiones/0032-capa-servicios-duena-del-flujo.md +++ b/docs/decisiones/0032-capa-servicios-duena-del-flujo.md @@ -10,7 +10,7 @@ [0033](0033-producto-library-centric-grafo-proyeccion.md) (posicionamiento library-centric), [0035](0035-ingesta-multipuerta-resolucion-doi.md) (ingesta multi-puerta + resolución DOI→ID son operaciones de servicio). -- **Encuadre:** [Nota 18](../Notas/18-flujo-canonico-biblioteca.md) (flujo canónico paso a paso). +- **Encuadre:** Nota 18 (flujo canónico paso a paso). - **Epic:** GUI local [#34](https://github.com/complexluise/bib2graph/issues/34) (iterada post-MVP). ## Contexto diff --git a/docs/decisiones/0033-producto-library-centric-grafo-proyeccion.md b/docs/decisiones/0033-producto-library-centric-grafo-proyeccion.md index d645596..e45d2e1 100644 --- a/docs/decisiones/0033-producto-library-centric-grafo-proyeccion.md +++ b/docs/decisiones/0033-producto-library-centric-grafo-proyeccion.md @@ -9,8 +9,8 @@ - **Relacionada con:** [0009](0009-biblioteca-viva-duckdb.md) (biblioteca viva = unidad de trabajo), [0032](0032-capa-servicios-duena-del-flujo.md) (el servicio dueño del flujo lo habilita), [0034](0034-etiquetado-tabla-tags-lateral.md) (etiquetado, parte del ejercicio bibliotecario). -- **Encuadre:** [Nota 16](../Notas/16-retroalimentacion-gui-mvp.md) §Re-priorización/§H1 + - [Nota 18](../Notas/18-flujo-canonico-biblioteca.md). **Decidido por el PO (2026-06-18).** +- **Encuadre:** Nota 16 §Re-priorización/§H1 + + Nota 18. **Decidido por el PO (2026-06-18).** - **Epic:** GUI local [#34](https://github.com/complexluise/bib2graph/issues/34). ## Contexto diff --git a/docs/decisiones/0034-etiquetado-tabla-tags-lateral.md b/docs/decisiones/0034-etiquetado-tabla-tags-lateral.md index 49cde2c..a7d4164 100644 --- a/docs/decisiones/0034-etiquetado-tabla-tags-lateral.md +++ b/docs/decisiones/0034-etiquetado-tabla-tags-lateral.md @@ -8,8 +8,8 @@ (etiquetar es parte del ejercicio bibliotecario primario), [0011](0011-thesaurus-multilingue.md)/ [0031](0031-preprocesamiento-automatico-en-ingesta.md) (tesauro/topics = camino a taxonomía), [0024](0024-orden-d3-columna-secuencia-duckdb.md) (patrón de tablas hermanas fuera del `corpus_hash`). -- **Encuadre:** [Nota 16](../Notas/16-retroalimentacion-gui-mvp.md) §H1/§H1b + - [Nota 17](../Notas/17-validacion-tercero-gate34.md) §BUG-2 + [Nota 18](../Notas/18-flujo-canonico-biblioteca.md). +- **Encuadre:** Nota 16 §H1/§H1b + + Nota 17 §BUG-2 + Nota 18. **Decidido por el PO (2026-06-18): tags libres ahora, tabla lateral, sin BIBFRAME.** - **Epic:** GUI local [#34](https://github.com/complexluise/bib2graph/issues/34). diff --git a/docs/decisiones/0035-ingesta-multipuerta-resolucion-doi.md b/docs/decisiones/0035-ingesta-multipuerta-resolucion-doi.md index 659e085..a508c95 100644 --- a/docs/decisiones/0035-ingesta-multipuerta-resolucion-doi.md +++ b/docs/decisiones/0035-ingesta-multipuerta-resolucion-doi.md @@ -8,8 +8,8 @@ (`seed --from-bib`, 3er modo BibTeX sin red), [0032](0032-capa-servicios-duena-del-flujo.md) (ingesta y resolución viven en `service/`), [0031](0031-preprocesamiento-automatico-en-ingesta.md) (ambas puertas comparten `normalize_and_dedup`). -- **Encuadre:** [Nota 17](../Notas/17-validacion-tercero-gate34.md) §GAP-1/§GAP-2 + DECISIÓN DEL PO + - [Nota 18](../Notas/18-flujo-canonico-biblioteca.md). **Decidido por el PO (2026-06-18): el flujo +- **Encuadre:** Nota 17 §GAP-1/§GAP-2 + DECISIÓN DEL PO + + Nota 18. **Decidido por el PO (2026-06-18): el flujo BibTeX/archivo es de PRIMERA CLASE.** - **Epic:** GUI local [#34](https://github.com/complexluise/bib2graph/issues/34). - **AS-BUILT (0.8, 2026-06-22):** se grada a Aceptada y se implementa el **core de resolución** diff --git a/docs/decisiones/0037-superficie-cli-10-verbos-ciclo.md b/docs/decisiones/0037-superficie-cli-10-verbos-ciclo.md index 93456f4..c028241 100644 --- a/docs/decisiones/0037-superficie-cli-10-verbos-ciclo.md +++ b/docs/decisiones/0037-superficie-cli-10-verbos-ciclo.md @@ -34,7 +34,7 @@ conteos del corpus, sin modelo generativo. - **Origen:** Discussion [#127](https://github.com/complexluise/bib2graph/discussions/127), comentario *"Propuesta de convergencia: superficie agents-first para 0.10.0 (más es menos)"*. - Encuadre: [Nota 05](../Notas/05-ciclo-investigacion-humano.md) (el ciclo de investigación humano) y + Encuadre: Nota 05 (el ciclo de investigación humano) y la **nota de sesión 20** (`docs/Notas/20-ax-agente-cli-redes-vacias.md` — AX de un agente en frío: *"redes vacías con cara de éxito"*; nota de sesión, **aún no versionada en `dev`**, citada como encuadre empírico). @@ -59,7 +59,7 @@ solapamientos** que un agente —y un humano— tienen que desambiguar sin que e Dos hechos de diseño ordenan la salida: -- **La superficie ES el ciclo de investigación.** La [Nota 05](../Notas/05-ciclo-investigacion-humano.md) +- **La superficie ES el ciclo de investigación.** La Nota 05 modela el ciclo humano (Kuhlthau/Ellis/Bates/Pirolli/Wohlin): IDEA → SEMILLAS → CHAINING → BROWSING/DIFERENCIAR → ORGANIZAR → SENSEMAKING → CURAR → MONITOREAR, **iterativo y no lineal**. Una superficie que **mapea 1:1 ese ciclo** es legible sin manual: el verbo *es* el paso. @@ -176,7 +176,7 @@ diagnostica antes** —el agente no se queda con una "cara de éxito" vacía. **Lo que se gana** - **El ciclo se vuelve legible y one-shot.** La superficie mapea 1:1 los pasos de la - [Nota 05](../Notas/05-ciclo-investigacion-humano.md); un agente (o un humano) infiere el flujo sin + Nota 05; un agente (o un humano) infiere el flujo sin manual: el verbo *es* el paso. El default sin curar deja correr `init→seed→chain→build→read` de punta a punta. - **Menos superficie, menos solapamiento.** De ~20 subcomandos con 6 solapamientos a **10 verbos**; diff --git a/docs/decisiones/README.md b/docs/decisiones/README.md index 2488c5d..51d51d8 100644 --- a/docs/decisiones/README.md +++ b/docs/decisiones/README.md @@ -6,7 +6,7 @@ crea un ADR nuevo que la supersede; no se reescribe la historia. Los refinamient revierten el principio se anotan como **bloques de "Enmienda" fechados** dentro del propio ADR (el cuerpo original queda como historia). -**Tras el red-team del AS-BUILT v0.2** ([Nota 06](../Notas/06-critica-as-built-v0.2.md)) el PO +**Tras el red-team del AS-BUILT v0.2** (Nota 06) el PO bloqueó un nuevo modelo conceptual (2026-06-15): el **producto no usa IA generativa** (ADR 0022); el scent es **bibliométrico determinista** (0020 enmendado); el ciclo es un **FSM cíclico de dominio** (0016 enmendado); **identidad ≠ procedencia** (0017 enmendado); y hay una **capa base de @@ -39,7 +39,7 @@ Qué se vuelve posible/fácil y qué se vuelve costoso/imposible. Trade-offs hon > Los ADR se numeran **por orden de creación**, no se reservan en general. **0027** (pivote de > posicionamiento GUI) y **0028** (arquitectura GUI/API + capa de servicios) existen ya como -> *Aceptada* (firmados 2026-06-18), derivados de la [Nota 12](../Notas/12-arquitectura-gui-encuadre.md) +> *Aceptada* (firmados 2026-06-18), derivados de la Nota 12 > (revisada 2026-06-18): **0027 gatea 0028** y enmienda el PRD §3/§5.2. > **Supersedidos por [0040](0040-retiro-gui-local.md)** (2026-06-28): la GUI local se **retira de la > librería** (fuera del foco; el core es CLI/agente-native). 0027/0028 y las Notas de diseño @@ -80,10 +80,10 @@ Qué se vuelve posible/fácil y qué se vuelve costoso/imposible. Trade-offs hon | [0029](0029-workspace-por-investigacion.md) | Workspace por investigación: carpeta autocontenida (`workspace.json` + db + redes/snapshots/exports) + resolución ambiente | **Aceptada — AS-BUILT** (2026-06-16; remanentes #32 cerrados 2026-06-17). **Enmienda BREAKING #75 (2026-06-17):** `--store` eliminado del CLI y fin del modo degenerado — la carpeta con `workspace.json` es la única unidad canónica; `.duckdb` legacy se adopta con `b2g init .`. Enmienda 0009/0019/0021; prerequisito GUI (#34) | | [0030](0030-ecuacion-declarativa-corpus-ejemplo.md) | Ecuación declarativa (`equation.yaml`, `seed --spec`) + `restore` de corpus curado (sin red) + corpus de ejemplo commiteado (`examples/valoraciones/`) + `seed --from-bib` (BibTeX) + filtro de año | **Aceptada — AS-BUILT** (9a + 9b + Ciclo 10, 2026-06-17): `restore`+`equation.yaml` cargable; `examples/valoraciones/` + gate R2; **`seed --from-bib` + `examples/bibtex/` + filtro de año real (#50 cerrado)**. Enmienda 0029; relacionada 0005/0006/0007/0016/0017/0018; prereq. Ciclo #33 → gate GUI (#34) | | [0031](0031-preprocesamiento-automatico-en-ingesta.md) | Preprocesamiento automático en la ingesta (normalize + dedup sobre el corpus completo mergeado, cross-biblioteca); `rapidfuzz` al núcleo (`[dedup]` eliminado); `thesaurus` = único paso explícito (18° subcomando, transversal); `persist_replace`/`overwrite_corpus` | **Aceptada — AS-BUILT** (2026-06-18, #88). **Supersede en parte [0026](0026-dedup-fuzzy-determinista.md)** (invocación del dedup) y la enmienda `[dedup]` de [0005](0005-dependencias-extras.md). Relacionada 0011/0017/0022/0024/0016; revisión asistida de clusters → epic GUI (#34) | -| [0032](0032-capa-servicios-duena-del-flujo.md) | La capa de servicios (`service/`) es dueña del loop bibliográfico completo (ingesta/resolución/enrich/curación/tags/forrajeo/proyección); CLI/API/GUI = adaptadores finos; migración por demanda | **Propuesta** (2026-06-18). **Extiende [0028](0028-arquitectura-gui-api-capa-servicios.md)** (de reads+curate a flujo entero). Relacionada 0010/0021/0027/0033/0035. Encuadre: [Nota 18](../Notas/18-flujo-canonico-biblioteca.md) | -| [0033](0033-producto-library-centric-grafo-proyeccion.md) | Producto library-centric: la vista de Biblioteca (buscar/navegar/etiquetar/curar) es la superficie primaria; el grafo es proyección downstream; BIBFRAME fuera | **Propuesta** (2026-06-18). **Refina [0027](0027-pivote-posicionamiento-gui-local.md)** (puerta de entrada de la GUI, no revierte). Relacionada 0009/0032/0034. Encuadre: Notas [16](../Notas/16-retroalimentacion-gui-mvp.md)/[18](../Notas/18-flujo-canonico-biblioteca.md) | -| [0034](0034-etiquetado-tabla-tags-lateral.md) | Etiquetado en tabla LATERAL `paper_tags` (no toca `CORPUS_SCHEMA`, esquiva BUG-2); tags libres → taxonomía fase 2 (SKOS + OpenAlex topics, no BIBFRAME); fuera del `corpus_hash` | **Propuesta** (2026-06-18). Relacionada 0009/0023/0006/0033/0011/0031/0024/0017. **Deja abierta** la extensibilidad general del schema (BUG-2). Encuadre: Notas [16](../Notas/16-retroalimentacion-gui-mvp.md)/[17](../Notas/17-validacion-tercero-gate34.md) | -| [0035](0035-ingesta-multipuerta-resolucion-doi.md) | Ingesta de doble puerta (online + archivo) misma cadena/corpus; resolución DOI→OpenAlex ID como servicio compartido (cierra GAP-1/GAP-2); import multi-formato (RIS/EndNote/CSV); BibTeX/archivo = primera clase | **Propuesta** (2026-06-18). **Revisa "BibTeX secundaria" de [0007](0007-openalex-backbone.md)** (en la ingesta). Relacionada 0018/0030/0032/0031. Encuadre: [Nota 17](../Notas/17-validacion-tercero-gate34.md) | +| [0032](0032-capa-servicios-duena-del-flujo.md) | La capa de servicios (`service/`) es dueña del loop bibliográfico completo (ingesta/resolución/enrich/curación/tags/forrajeo/proyección); CLI/API/GUI = adaptadores finos; migración por demanda | **Propuesta** (2026-06-18). **Extiende [0028](0028-arquitectura-gui-api-capa-servicios.md)** (de reads+curate a flujo entero). Relacionada 0010/0021/0027/0033/0035. Encuadre: Nota 18 | +| [0033](0033-producto-library-centric-grafo-proyeccion.md) | Producto library-centric: la vista de Biblioteca (buscar/navegar/etiquetar/curar) es la superficie primaria; el grafo es proyección downstream; BIBFRAME fuera | **Propuesta** (2026-06-18). **Refina [0027](0027-pivote-posicionamiento-gui-local.md)** (puerta de entrada de la GUI, no revierte). Relacionada 0009/0032/0034. Encuadre: Notas 16/18 | +| [0034](0034-etiquetado-tabla-tags-lateral.md) | Etiquetado en tabla LATERAL `paper_tags` (no toca `CORPUS_SCHEMA`, esquiva BUG-2); tags libres → taxonomía fase 2 (SKOS + OpenAlex topics, no BIBFRAME); fuera del `corpus_hash` | **Propuesta** (2026-06-18). Relacionada 0009/0023/0006/0033/0011/0031/0024/0017. **Deja abierta** la extensibilidad general del schema (BUG-2). Encuadre: Notas 16/17 | +| [0035](0035-ingesta-multipuerta-resolucion-doi.md) | Ingesta de doble puerta (online + archivo) misma cadena/corpus; resolución DOI→OpenAlex ID como servicio compartido (cierra GAP-1/GAP-2); import multi-formato (RIS/EndNote/CSV); BibTeX/archivo = primera clase | **Propuesta** (2026-06-18). **Revisa "BibTeX secundaria" de [0007](0007-openalex-backbone.md)** (en la ingesta). Relacionada 0018/0030/0032/0031. Encuadre: Nota 17 | | [0036](0036-identidad-source-id-agnostica-doi-ancla.md) | Identidad de fuente agnóstica: DOI como ancla universal, `source_id` genérico, motor de extracción intercambiable (tabla lateral `external_ids` 1↔N) | **Aceptada — AS-BUILT** (0.8, 2026-06-22): rename `openalex_id`→`source_id`, inversión de `_compute_id` (`doi > source_id > tt`), desacople del núcleo, infra `external_ids`, migración de `examples/valoraciones` (#118/#119). **Enmienda 0007/0013**; refuerza 0018; relacionada 0035/0034/0015. Población de `external_ids` y selector `--source` diferidos al 2º motor (#120) | | [0037](0037-superficie-cli-10-verbos-ciclo.md) | Superficie CLI de 0.10.0: **10 verbos agents-first** que mapean el ciclo (INIT→SEED→CHAIN→CURATE→BUILD→READ→EXPORT/SNAPSHOT, STATUS transversal); `status` como mapa (`next_best_action` + **preview por-red "qué se materializa" (e)** + **maturity-stamp del one-shot (f)**, campos aditivos); `curate`/`read` noun-verb; `monitor`→`chain --since`; aliases de retrocompat | **Aceptada** (2026-06-26). **Enmienda [0021](0021-cli-agente-native-contrato.md)** (consolida 12→10; envelope `schema="1"`/exit/FSM intactos). Relacionada 0010/0016/0029/0035/0036/0032/0033; no introduce IA (0022). Origen: Discussion [#127](https://github.com/complexluise/bib2graph/discussions/127); issues #76/#132 | | [0038](0038-destino-verbos-huerfanos-0037.md) | Destino de los 5 verbos huérfanos que el 0037 no nombró: `gui` se mantiene fuera de los 10 (0027/0028); `enrich`→absorbido en `chain`/`build`; `restore`→`snapshot restore`; `thesaurus`→retirado; `resolve`→retirado (ruta única `seed --resolve`). Fija: ventana de deprecación cierra en **0.11.0**; `build --scope=all` default; forma de `maturity` en `docs/API.md` | **Aceptada** (2026-06-27). **Enmienda [0037](0037-superficie-cli-10-verbos-ciclo.md)** (cierra el conteo "10 verbos"); revisa el `thesaurus` de [0031](0031-preprocesamiento-automatico-en-ingesta.md); renombre de [0030](0030-ecuacion-declarativa-corpus-ejemplo.md); refuerza 0035; envelope `schema="1"`/exit/FSM intactos. Contexto: issues #149/#34 | diff --git a/docs/decisiones/registro-ia.md b/docs/decisiones/registro-ia.md index b193223..93f1292 100644 --- a/docs/decisiones/registro-ia.md +++ b/docs/decisiones/registro-ia.md @@ -100,7 +100,7 @@ > tomado por el ADR de proyección de redes (Hito 2). Para no reescribir historia, los ADR nuevos > usan **`0015`–`0019`**. La separación `filter`/`curate` (punto 4 del acta) **no recibió ADR > propio**: es una decisión de superficie CLI/roadmap, no de arquitectura — se refleja en -> [`../ROADMAP.md`](../ROADMAP/README.md) (Hito 6) y [`../API.md`](../API.md) (§convenciones CLI). +> `../ROADMAP.md` (Hito 6) y [`../API.md`](../API.md) (§convenciones CLI). --- @@ -319,7 +319,7 @@ > **Reconciliación de docs (arquitecto, 2026-06-16):** ADR 0016 (nota "implementado en R3"), ADR 0021 > (envelope de `status` con `curation_available`/`round` aditivos, `schema="1"`), ROADMAP (Hito R3 ✅ + > banner as-built), ARCHITECTURE.md (§5.5 FSM → `cycle.py` AS-BUILT R3), API.md (§convenciones CLI + -> bloque `cycle.py`), CHANGELOG (R3 marcado). La [Nota 05](../Notas/05-ciclo-investigacion-humano.md) +> bloque `cycle.py`), CHANGELOG (R3 marcado). La Nota 05 > ya describía el ciclo correcto y **no requirió cambios** (R3 la **implementa**, no la corrige). --- @@ -330,7 +330,7 @@ > [0020](0020-metodo-forrajeo-scent-filtros-reject.md) (scent = proyectores), > [0022](0022-producto-sin-ia-generativa.md) (el producto no usa IA) y > [0008](0008-wedge-forrajeo.md) (tensiones retiradas). Cierra la RAÍZ 1 (parte de IA) de la -> [Nota 06](../Notas/06-critica-as-built-v0.2.md). **291 tests** verdes, mypy strict / ruff limpios; el +> Nota 06. **291 tests** verdes, mypy strict / ruff limpios; el > núcleo de scent depende del núcleo de proyección (puro), no al revés. **Verifier: APRUEBA CON > RESERVAS** (3 cuestiones de método); el **steering arquitectónico (2026-06-16)** las resolvió. @@ -357,7 +357,7 @@ > ADR 0022 (AS-BUILT: sin IA construido), ROADMAP (Hito R4 ✅ TERMINADO + DoD reconciliado), > ARCHITECTURE.md (§3.5 scent→proyectores AS-BUILT R4), API.md (§5 scent bibliométrico construido), > CHANGELOG (R4 marcado). README/AI_DISCLOSURE/AGENTS ya describían el retiro de `[llm]`/IA en pasado y -> **no requirieron limpieza adicional**. La [Nota 05](../Notas/05-ciclo-investigacion-humano.md) §4 ya +> **no requirieron limpieza adicional**. La Nota 05 §4 ya > prometía "la bibliometría ES el information scent" y **no requirió cambios** (R4 la **implementa**). --- @@ -366,7 +366,7 @@ > Último hito de la tanda de remediación. **No cambia el modelo conceptual; endurece lo construido.** > Cierra la RAÍZ 3 (no corre a escala + bug del contrato agente-native) y el catálogo de secundarios de -> la [Nota 06](../Notas/06-critica-as-built-v0.2.md). **319 tests** verdes +> la Nota 06. **319 tests** verdes > (`tests/unit/test_r5_robustness.py` + ajustes), mypy strict / ruff check+format limpios. > **Verifier: APRUEBA** (reservas cerradas). Con R5 la **tanda R1–R5 queda COMPLETA**. @@ -403,7 +403,7 @@ > completada), ROADMAP (Hito R5 ✅ + banner as-built + DoD reconciliado: batching diferido; tanda R1–R5 > COMPLETA), ARCHITECTURE.md (§3.1 bulk-load, §6.3 UTF-8/store-readonly, §8 footguns), API.md (PRISMA > lanza, store read-only, `.bib` lanza, `lib_version` "unknown", forward `DependencyError`+retry), -> CHANGELOG (R5 ✅ Fixed + Changed de comportamiento). La [Nota 06](../Notas/06-critica-as-built-v0.2.md) +> CHANGELOG (R5 ✅ Fixed + Changed de comportamiento). La Nota 06 > recibió una nota corta de cierre (rastro histórico, sin reescribir hallazgos). --- diff --git a/mkdocs.yml b/mkdocs.yml index 008ccc5..4b108ed 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -112,7 +112,9 @@ markdown_extensions: - mkdocs-click # Páginas que se construyen y son enlazables por URL, pero NO aparecen en el -# sidebar (los 38 ADRs viven en su índice docs/decisiones/README.md). +# sidebar. Las 38 ADRs viven en su índice docs/decisiones/README.md (visible +# por URL — ejercicio de transferencia — pero no en el nav principal, para no +# abrumar al usuario final ni al asistente de IA). not_in_nav: | /decisiones/0*.md /decisiones/registro-ia.md @@ -151,7 +153,6 @@ nav: - Contribuye: - Contribuir: contributing.md - Arquitectura: ARCHITECTURE.md - - Decisiones de diseño (ADRs): decisiones/README.md - Requisitos del producto (PRD): PRD.md - Versionado: versioning.md - IA en el desarrollo: ai-disclosure.md