Add manuscript scaffold, Figure 1, slide deck, and Pages site

[cmungall]

Summary

Adds docs/manuscript/ — a pre-results manuscript scaffold plus a literature-grounded background, a Figure 1 schematic, an HTML slide deck, and a GitHub Pages workflow to publish them. No code under src/, config/, data/, or skills/ is touched; this is documentation only. Rebased onto current main, so the diff is just the four docs commits.

What's included

Manuscript drafts (docs/manuscript/)

• 03_methods.md — drafted from the locked evaluation design (config/, src/, skills/).
• 01_introduction.md, 02_background.md — drafted and cited from a deep literature survey of (a) the latest agentic-curation / LLM-for-data-work research (2024–2026) and (b) environmental harmonization, data cleaning, ontologies, provenance, and benchmarks.
• 00_abstract.md, 04_results.md, 05_discussion.md, 06_conclusion.md — scaffolds with [[PLACEHOLDER]] markers tied to the metrics/figures the analysis pipeline will generate.
• references.md — ~90 sources with per-source verification status; every in-text citation key resolves.
• research_notes.md — survey provenance, comparable-work ranking, verification TODOs.
• README.md, figures_and_tables.md, index.html — section index, display-item manifest, landing page.

Figure 1 (docs/manuscript/figures/)

• figure1_workflow.mmd (Mermaid source) + static figure1_workflow.svg / .png (rendered offline) + figure1_workflow.html (live render). Shows the curator → bundle → harmonizer → code+mapping flow, the three evaluation modes, and the cell-by-cell output-equivalence endpoint.

Slide deck (docs/manuscript/slides/index.html)

• 15-slide reveal.js deck summarizing motivation, the agent pair, the two-phase / three-mode design, output-equivalence metrics, related-work positioning, results placeholders, and limitations.

Offline + hosting

• reveal.js 5.2.1 and Mermaid 11.16.0 are vendored under docs/manuscript/vendor/; the deck and figure render with no external network (verified with all network blocked).
• .github/workflows/pages.yml publishes docs/manuscript/ to GitHub Pages.

One manual step to go live

The Pages deploy needs Pages enabled once: Settings → Pages → Build and deployment → Source: "GitHub Actions." The workflow token can't auto-enable it (org policy). Once enabled and this PR is merged, the workflow deploys from main to roughly https://bioepic-data.github.io/data-harmonization-eval/.

Notes

• All numbers in results/discussion are placeholders pending the experimental run — nothing reports a value the analysis pipeline hasn't produced.
• References flagged "snippet-only" in references.md should be DOI-confirmed before manuscript submission (see research_notes.md).

🤖 Generated with Claude Code

---

Generated by Claude Code

[claude]

Claude finished @cmungall's task —— View job

---

PR Review: Add manuscript scaffold, Figure 1, slide deck, and Pages site

• Read key files for context
• Review GitHub Actions workflow
• Review manuscript content
• Review slide deck and Figure 1
• Review vendored libraries
• Post comprehensive feedback

---

This is a high-quality documentation PR. The writing is rigorous, the evaluation design is methodologically sound, and the tooling choices (vendored libraries, offline-first rendering) are appropriate. Here are the observations across the review dimensions:

---

GitHub Actions Workflow (.github/workflows/pages.yml)

Minor issues:

1. Branch trigger should be removed before merge. Line 11 includes the PR branch (claude/agentic-curation-research-docs-6dgt7l) in the push: trigger. This is presumably a development convenience but it will cause a Pages deploy attempt on every push to this branch. It should be removed before or immediately after merging so only main triggers deploys.

2. enablement: true on configure-pages may not work as expected. The PR description correctly notes that auto-enablement requires a manual step (Settings → Pages → Source: "GitHub Actions"). The enablement: true parameter will attempt API-based enablement which is often blocked by org policy — the workflow may simply fail on first run until Pages is manually enabled. This is documented in the PR body so it's not a bug, but a comment in the workflow YAML itself would prevent future confusion.

3. No build step / artifact validation. The workflow deploys the raw docs/manuscript/ directory with no integrity check. This is fine for a static HTML/Markdown site, but worth noting — if Markdown files are the primary content and the Pages host doesn't render them, users landing on references.md directly will see raw text (the index.html notes this; it's acceptable but worth keeping in mind).

4. Concurrency cancel-in-progress: true is a sensible default for a docs site.

---

Manuscript Content

Strengths:

• The three-property evaluation design (output-centric, decomposable, honest generalization) is clearly motivated and well-argued throughout.
• The TODO markers ([[PLACEHOLDER]]) and > **Status:** callouts make the pre-results nature of each section unambiguous — good discipline.
• The methods section (03_methods.md) maps faithfully to the codebase paths (src/schemas/, config/, etc.).

Issues to address before submission (not merge blockers):

1. [AgentSkills-2025] citation is a placeholder. references.md line 258 notes this should point to "primary engineering blog / agentskills.io" at submission; research_notes.md echoes this. The current stub cites https://www.anthropic.com/ — acceptable as a working note but needs a real primary reference before journal submission.

2. "80% of time on data prep" provenance is flagged throughout. The research_notes.md correctly warns that [Lohr-2014] and [CrowdFlower-2016] have weak provenance for this claim. The slide deck (slide 2) already includes the hedged label "provenance weak" in the citation, which is commendable. The introduction (01_introduction.md:34) should also add a similar hedge or switch primary attribution to the peer-reviewed [Kandel-2012] reference.

3. [JudgeReliability-2026] is a 2026 arXiv preprint (arXiv:2603.05399) noted as [S — 2026 preprint, confirm]. Given the knowledge cutoff, this should be verified against the actual paper before submission.

4. Gold dataset count inconsistency. 03_methods.md line 103 has a > TODO: the mapping JSON has indices 0–27 with several excluded/auxiliary entries; the text says "19 expert-harmonized datasets." This should be reconciled at results-time.

5. [ENVO] / [Buttigieg-2013] conflict-of-interest note — research_notes.md line 107 correctly flags that C. J. Mungall (the project lead) is a co-author on the ENVO paper. If this manuscript is submitted for journal peer review, a COI disclosure may be required.

---

Figure 1 (figures/figure1_workflow.mmd + .html)

Minor diagram issue: In figure1_workflow.mmd (and the duplicate in slides/index.html), Mode 2 (oracle) scores the output of the harmonizer when fed a gold bundle, but there is no explicit dashed scored-edge from the oracle path into M2 — only B -. scored .-> M1 and OUT -. scored .-> M3 are drawn. A reader following the diagram alone may not immediately see how Mode 2 is evaluated. Adding OUT -. scored (oracle) .-> M2 or a similar edge would make the diagram self-contained.

The HTML renderers (figure1_workflow.html and slides/index.html) use securityLevel: "loose" for Mermaid, which allows arbitrary HTML inside diagram labels (e.g., the <b> tags on "Curator" and "Harmonizer" nodes). This is intentional and used correctly here, but is worth documenting as a conscious choice since "loose" disables XSS protections in Mermaid — safe here because the diagram source is repo-controlled, not user-supplied.

---

Slide Deck (slides/index.html)

• Slide 5 uses securityLevel:"loose" for the inline Mermaid diagram — same note as above.
• The font-weight values use non-standard integers (e.g., font-weight:680, font-weight:740) which are technically valid CSS but will be rounded to the nearest supported weight by most browsers/fonts. They function as 700 in practice — cosmetic, not a bug.
• The mermaid.run() → Reveal.initialize() ordering in the script (lines 409–418) is correct: Mermaid is awaited before Reveal initializes, preventing layout reflow issues.

---

Vendored Libraries

• vendor/VERSIONS.txt pins reveal.js 5.2.1 and mermaid 11.16.0 — good practice for reproducibility.
• The vendored files are served from the repo, which keeps the published site fully offline-capable as advertised.
• No integrity/subresource checks (SRI hashes) are present, but these are vendor-committed files in the repo rather than CDN fetches, so this is acceptable.

---

Overall Assessment

This is a well-crafted, ready-to-merge documentation PR. The manuscript scaffold accurately reflects the codebase design, placeholders are clearly marked, and the offline-first Pages deployment is a thoughtful choice. The two concrete changes I'd suggest before merging are:

1. Remove the PR branch from the workflow's push: trigger (.github/workflows/pages.yml line 11) to avoid spurious Pages deploys after merge.
2. (Optional, pre-submission) Add an explicit oracle-path edge to Figure 1 for diagram clarity.

All other items are pre-submission writing TODOs that are already tracked in research_notes.md — no action needed for this PR.