fn_registry/docs/capabilities/papers.md

papers — papers académicos reproducibles

Grupo de capacidad para producir papers académicos dentro de fn_registry: investigación con hipótesis falsables, experimentos reproducibles, análisis estadístico honesto y escritura en formato IMRaD. Cada paper es un artefacto nuevo en papers/<NNNN-slug>/ que reutiliza infraestructura existente (skill deep-research para la revisión de literatura, grupo eda para el análisis, motor md→PDF de datascience, patrón de verificación adversarial del orquestador) y añade lo que falta como funciones del registry.

Diseño completo y decisiones: reports/0001-2026-06-30-papers-system-design.md.

Regla de oro anti paper-mill: una hipótesis que podía fallar + un experimento con riesgo real de refutación + estadística que no es teatro. Si no hay riesgo de refutación, no es un paper. Los claims nunca superan a la evidencia. El antídoto al HARKing es el pre-registro: el plan de análisis se congela antes de mirar los datos.

Estructura del artefacto

papers/0001-mi-paper/
  paper.md            # frontmatter (title, slug, authors, date, status, phase, tags, domain, hypothesis_id) + cuerpo IMRaD
  preregistration.md  # H0/H1 + plan de análisis CONGELADO (frozen_at + content_hash) antes de correr
  references.md       # bibliografía
  experiments/        # código / notebooks por experimento (exp01_*, exp02_*)
  data/               # crudos + procesados (gitignored si pesa)
  figures/            # gráficos generados
  reviews/            # outputs del peer-review adversarial
  out/                # paper.pdf — entregable final
  .git/               # SOLO cuando promociona a fase publishable (sub-repo Gitea)

papers/ está gitignored en el repo padre (solo papers/.gitkeep se versiona): un paper en fase interna no contamina el repo. Al promocionar a status: publishable se vuelve sub-repo Gitea dataforge/<slug> (como apps y analyses).

Fases (campo phase de paper.md)

question → review → hypothesis → design → running → analysis → writing → internal-review
  → [DONE interno]  → polish → submitted          [solo en fase publishable]

Funciones

ID	Pureza	Estado	Qué hace
init_paper_bash_pipelines	impure	✅ disponible	Scaffold de papers/<NNNN-slug>/: calcula el siguiente NNNN, crea las subcarpetas, copia paper.md + preregistration.md con el frontmatter relleno (slug, title, date de hoy, phase: question, status: draft) y references.md vacío. NO hace git init (el paper arranca en fase interna local).
next_numbered_dir_bash_io	impure	✅ disponible	Dado un directorio, devuelve el siguiente número incremental de 4 dígitos (0001, 0002, …) escaneando los subdirs con prefijo NNNN-. Helper de numeración de init_paper (reutilizable por reports/issues).
preregister_hypothesis	impure	🚧 en construcción (flota)	Congela el preregistration.md (H0/H1 + plan de análisis) con frozen_at + content_hash, pasa status a frozen y escribe hypothesis_id en paper.md. Mata el HARKing: tras congelar, el plan no se edita.
cohens_d (effect size)	pure	🚧 en construcción (flota)	Tamaño del efecto (Cohen's d) entre dos grupos. Reporta magnitud, no solo significancia.
confidence_interval	pure	🚧 en construcción (flota)	Intervalo de confianza de una métrica (media/diferencia).
holm_bonferroni	pure	🚧 en construcción (flota)	Corrección de comparaciones múltiples (Holm-Bonferroni / FWER) para el plan de análisis.
render_paper_pdf	impure	🚧 en construcción (flota)	Markdown IMRaD (paper.md + figuras) → out/paper.pdf, reutilizando el motor md→PDF del grupo eda/datascience.

Las funciones estadísticas reutilizan lo que ya exista en datascience (p.ej. fdr_correction_py_datascience cubre la corrección de comparaciones múltiples por FDR; el agente del rigor experimental decide si añade Holm-Bonferroni o reusa lo existente). Buscar antes de duplicar: mcp__registry__fn_search query="effect size" domain="datascience".

Peer review (no es función del registry)

El agente adversarial .claude/agents/paper-reviewer.md (🚧 en construcción por la flota) puntúa novedad, rigor, reproducibilidad y validez, e intenta refutar cada claim. Default a "failed" si la evidencia no soporta. Escribe su veredicto en reviews/. Es el equivalente al verificador adversarial del orquestador aplicado al paper.

Ejemplo canónico (end-to-end)

# 1. Scaffold del paper (fase question, local). Crea papers/0001-mi-paper/.
./fn run init_paper mi-paper --title "¿El bucle reactivo reduce las calls inline?" --domain datascience --tags registry,telemetria

# 2. Revisión de literatura → llena Related work (skill deep-research, fase review).
#    /deep-research "..."

# 3. Pre-registro: congela H0/H1 + plan de análisis ANTES de mirar datos (fase hypothesis).
./fn run preregister_hypothesis papers/0001-mi-paper      # 🚧 en construcción

# 4. Experimentos en papers/0001-mi-paper/experiments/ (fase running) →
#    análisis con el grupo `eda` + funciones de effect size / CI / corrección múltiple (fase analysis).

# 5. Escritura IMRaD en paper.md (fase writing) → render del entregable PDF.
./fn run render_paper_pdf papers/0001-mi-paper            # 🚧 en construcción → out/paper.pdf

# 6. Peer review adversarial (fase internal-review).
#    Agent(subagent_type="paper-reviewer", prompt="Revisa papers/0001-mi-paper ...")  # 🚧 en construcción

Fronteras

• NO es para reports de trabajo. Un report (reports/) es el entregable escrito de una tarea (resumen + evidencia + gaps); un paper es investigación con hipótesis falsable y experimento. Ver .claude/rules/reports.md.
• NO se indexa en registry.db en esta fase. No hay tabla papers ni entity_type paper (KISS); se añadiría con migración propia si se decide. Las funciones del grupo sí se indexan (viven en bash/functions/, python/functions/), pero los artefactos papers/<slug>/ no.
• NO hace git init en el scaffold. El paper arranca en fase interna local y gitignored. La promoción a sub-repo Gitea (fase publishable) es un paso manual posterior.
• NO soporta LaTeX/arXiv todavía. Formato elegido: Markdown como fuente + PDF como entregable. El soporte LaTeX se añadiría al promocionar un paper a fase publishable.

Estado

Fase de scaffolding. Disponible: estructura del artefacto, plantillas (docs/templates/paper.md, docs/templates/preregistration.md), pipeline init_paper + helper next_numbered_dir, esta página y el bloque gitignore de papers/. En construcción por la flota: preregister_hypothesis, funciones estadísticas (effect size / CI / corrección múltiple), render_paper_pdf y el agente paper-reviewer. Validación end-to-end con un paper piloto real: pendiente.