docs(papers): plain-English (eli5) rewrite + click-to-reveal glossed HTML - #28
Merged
Conversation
Runs the paper-eli5 skill over docs/paper/forge-gap-paper.md and lands the result at docs/papers/forge-gap-eli5.md. The rewrite mirrors the paper 1:1 — same headings, same paragraph order, nothing summarized, merged, dropped, or reordered. Only the language changes: smart-newcomer register, jargon translated on first use. Tables are reproduced verbatim, each followed by an italic "In plain words" gloss; figures keep their original images with rewritten captions; the references section is carried through byte-identical. Phase 3 verification passed clean: headings identical and in order, per-section paragraph counts equal to the source, per-section table/figure counts equal, references verbatim. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011AN32UGWb73wnnYhUktRQr
Runs the paper-gloss skill over the eli5 rewrite: every occurrence of each approved jargon term becomes a clickable button that reveals a plain-English expansion, plus a toggle-able glossary panel listing every term at once. The prose itself is never rewritten or interrupted — only wrapped. Self-contained single file: all CSS and JS inline, every figure embedded as a data URI, no external requests. Themed for light and dark, with the viewer's theme toggle overriding the OS preference in both directions. Phase 3 verification passed clean: occurrence coverage matches per term, no bare or overlapping/nested wrappers, dictionary symmetry both ways, per-section paragraph counts equal the eli5, zero wrappers inside tables/figures/citations/ references, self-contained, and every CSS variable defined in all four token blocks. Verified in a real browser: term clicks open the popover, Escape and re-click close it, the glossary panel lists every row, and no page-level horizontal scroll. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011AN32UGWb73wnnYhUktRQr
ksdisch
changed the title
ksdisch
marked this pull request as ready for review
July 27, 2026 14:31
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two deliverables over
docs/paper/forge-gap-paper.md, from thepaper-eli5andpaper-glossskills.docs/papers/forge-gap-eli5.md— a plain-English rewrite mirroring the paper 1:1: same headings, same paragraph order, nothing summarized, merged, dropped, or reordered. Tables verbatim, each followed by an italic "In plain words" gloss; all 6 figures keep their original image references (in this paper the caption lives in the alt text, so that is what carries the rewritten plain-English caption); References — including Wilson 1927 and Newcombe 1998 — byte-identical.docs/papers/forge-gap-eli5-glossed.html— the same document as a self-contained interactive page: 13 terms, 56 occurrences wrapped as click-to-reveal buttons, plus a 📖 glossary panel.📖 Read it here: https://claude.ai/code/artifact/5595b09c-d8f0-4d93-8488-ac3e8966b1f9
Source note
The paper itself is not on
main— it lives ondocs/paper-and-presenter-pack, the review-only branch behind open PR #22. This work is based offmainand cites the paper with that ref, so the two PRs are independent and neither blocks the other.Verification
eli5 (Phase 3, clean): headings 26/26 identical and in order · paragraphs 43/43 per section · 4 tables each glossed · 6 figures preserved · references byte-identical. Figure paths needed no rewriting —
../figures/resolves identically fromdocs/papers/as fromdocs/paper/, and all six targets exist.gloss (Phase 3, clean):
Wilson score intervalbeatsWilson,straddling zeroandstraddle zerokept distinct)<p>== 47 source paragraphs (43 prose + 4 gloss lines)[Wilson, 1927]and[Newcombe, 1998]citations, which are deliberately left unwrapped:root, dark media query, and bothdata-themeblocksVerified in Chromium: 56 buttons in the DOM, all 6 figures load, popover opens and closes via
Escape/re-click, panel lists all 13 rows, no horizontal scroll, zero JS errors.Docs-only change — no code, tests, figures, or existing
docs/spine files touched, socheck_docs.pyand the offline suites are unaffected.Notes
oracle— was dropped: its only occurrence in the rewrite is inside the inline code spanoracle.py, which is non-prose and never wrapped, so keeping the entry would have left it unused, which the spec forbids.