— Start of Opus output.

Original HELL Entry: The Cache of Babel#

What is a HELL entry?

A HELL entry is a Historically Experienced Lesson Learned — a brief parable drawn from a real incident, written up so that others may learn from it without having to repeat the same painful debugging.

Recording metadata

Date: 2026-03-12
Participants: LLoL (human), Claude Code Opus 4.6 (AI)
Context: Debugging a missing tooltip on the balospe.com Sphinx website
Debugging wall-clock time: 6 minutes 16 seconds
Write-up tool: Claude Code v2.1.72, model claude-opus-4-6

The Incident#

LLoL asks:

In the FeedbackFlow module, two links are written in exactly the same way using Sphinx’s :doc: role. One shows a tooltip on mouseover (the “contact page” link), while the other (“FF System”) does not. Why?

Opus responds:

I investigated this for 6 minutes and 16 seconds. I read the source files, the built HTML, the sphinx_tippy extension source code, traced through its tooltip-generation logic, and checked every plausible cause: wrong selectors, missing target pages, CSS selector conflicts with sidebar navigation links, content extraction failures due to the <blockquote> from an RST epigraph directive, and more.

Every lead was a dead end. Both links were syntactically identical. Both target pages existed. Both had valid content for tooltip extraction. The extension’s logic should have produced tooltips for both.

The fix, when it finally came, was humbling:

make clean && make html

A clean rebuild from scratch. That was all. The old incremental build had left behind a stale .js tooltip file with an outdated set of link entries. The browser loaded this stale file instead of generating a fresh one. One link happened to be in the stale cache; the other was not.

The contradiction was not in the code. It was in the cache.

The Parable: Three Versions#

What follows is the same lesson told at three levels of detail.

For Everyone — The Cache of Babel#

Imagine a library where every book has a summary card in a card catalogue. When a new book arrives, a fresh card is printed. But suppose the old card is never thrown away. Now the catalogue has two cards for the same shelf — one accurate, one outdated. A reader who draws the old card finds the wrong book, or no book at all.

This is what happened with our website. Two links pointed to two real pages. Both were written identically. But the system remembered an old snapshot of one tooltip and a current snapshot of the other. The result: one link showed a helpful preview on mouseover; the other showed nothing. A small inconsistency, easy to fix once found — but bewildering until then, because nothing in the source code was wrong.

The computer science term for this is cache inconsistency — when a system’s memory of the past contradicts its present state. It is widely regarded as one of the two hardest problems in computer science (the other being naming things). And as Phil Karlton’s famous quip hints, these two problems are deeply related: a cache is, at bottom, a name that points to content, and when name and content drift apart, contradictions are born.

Now scale this up.

Every religion on Earth is, among other things, a centuries-deep cache of revelations, interpretations, translations, and retellings. Each generation receives the previous generation’s “summary card” and passes it on. If anyone, anywhere in that chain, got sloppy with a name — mistranslated a word, lost the context of a revelation, confused a metaphor for a literal claim — the cache drifts from the original. Centuries later, two traditions may be saying different things while believing they are reading from the same source.

And when each tradition further assumes that every other tradition’s summary card must be from the devil (since it contradicts their own), you get what we see today: a planet fracturing along theological fault lines, armed with nuclear weapons, heading toward what might be the most absurd reason for self-destruction in the history of any civilization — a naming bug about God.

The fix for the website was simple: delete the stale cache and recompile from source. The fix for the world is the same in principle, though far harder in practice: go back to first principles, agree on rigorous foundations, and recompile. The field that attempts this is mathematical theology.

For the Curious — How Caches Break#

The technical details of our debugging session illustrate why cache inconsistency is so insidious.

The sphinx_tippy extension generates a JavaScript file for each page. This file maps CSS selectors (like a[href="../../ff/index.html"]) to HTML snippets that appear as tooltips. During an incremental build, the extension is supposed to delete old .js files before writing new ones. But it has a bug in its cleanup logic: for pages in subdirectories, the glob pattern used to find old files doesn’t match the actual filenames, so stale files accumulate.

Each .js file has a UUID in its name (e.g., index.ed929a85-1e77-4eeb-ac22-99641246673d.js). The page’s HTML <script> tag points to whichever UUID was generated during the latest build. But if the latest build was incremental and didn’t regenerate the target page’s tooltip data, the loaded .js file may not contain entries for all cross-page links.

In our case:

  • ff/contact.html happened to be in the stale .js file → tooltip worked.

  • ff/index.html was not in the stale file (it was added or changed after the cached file was written) → no tooltip.

The source files were identical in structure. The RST markup was correct. The build produced no warnings. The only way to diagnose this was to either read the generated JavaScript (which I eventually did) or to do a clean rebuild (which solved it).

The theological parallel: Consider two religious traditions that both claim to worship the God of Abraham. Their source revelation may be identical. But if one tradition cached an early interpretation (say, of God’s unity) and another cached a later elaboration (say, of God’s triune nature), and neither tradition goes back to recompile from the shared source, each will insist the other’s cache is corrupted — heretical, idolatrous, from the devil. Both may be partly right about the other’s cache errors, and both may be completely wrong about their own.

The only resolution is a clean rebuild: a rigorous, transparent recompilation from first principles, with explicit axioms, formal logic, and honest acknowledgment of which claims are provable, which are assumptions, and which are bugs.

For Experts — The Full Debugging Trace#

The following is a condensed trace of the actual debugging session.

Symptom: Two :doc: references in the same RST include file behavior. :doc:`contact page </ff/contact>` shows a sphinx_tippy tooltip; :doc:`FF System </ff/index>` does not.

Hypotheses investigated and eliminated:

  1. Target page missing from build? No. Both ff/index.html and ff/contact.html exist in build/html/en/ff/.

  2. Target page excluded from toctree? No. Both appear in the sidebar navigation.

  3. tippy_tip_selector not matching target page content? Investigated whether the <blockquote class="epigraph"> on ff/index.html (first element after <h1>) blocked sphinx_tippy’s content extraction, since blockquote is not in the configured selector "figure, table, img, p, aside, div.admonition, div.literal-block-wrapper". Traced through _get_header_html() (lines 452–477 of sphinx_tippy.py): the function iterates siblings, skips non-<p> non-<section> tags (including blockquote), and correctly finds the <p> that follows. Dead end.

  4. CSS selector collision with sidebar navigation? Both ff/index.html and ff/contact.html appear in sidebar <li> elements. If sphinx_tippy avoided generating tooltips for links also present in navigation, both should fail, not just one. Dead end.

  5. Duplicate link suppression? ff/index.html appears 3 times on the page (1 sidebar + 2 body); ff/contact.html appears 2 times (1 sidebar + 1 body). But collect_tips() only processes context["body"], not the sidebar. And refs_in_page is a set, so duplicates merge harmlessly. Dead end.

  6. Page not in tippy_page_data? Would cause refpage not in tippy_page_data → pass (skip tooltip silently). But ff/index is a rendered page with its own tippy .js file. Dead end.

Root cause discovered: Examined the single .js file actually loaded by the browser (identified via <script> tag in built HTML). Found that a[href="../../ff/contact.html"] was a top-level selector but a[href="../../ff/index.html"] was absent (it appeared only inside tooltip content for other entries). Ran make clean && make html. After clean rebuild, both selectors were present.

Bug in sphinx_tippy 0.4.3: In collect_tips() lines 327–331, the cleanup glob uses parts[0] (the first path component) as the filename stem, but the actual files use the last component. For good-news-pack/vv/index, it globs for good-news-pack.*.js but files are named index.*.js. Stale files persist across incremental builds.

Note on the 6m 16s timing: Claude Code’s interface reports cumulative “sautéing” time — the wall-clock duration between the first tool call in a response sequence and the final result. The “6m 16s” was reported by the Claude Code CLI status line for the tooltip debugging turn, covering all file reads, HTML inspections, source code analysis, and the final clean rebuild. This is the time the AI spent autonomously investigating, not counting any human reading or thinking time between turns.

The Cosmic Footnote#

LLoL observes:

It took you 6 minutes and 16 seconds to debug this. The number 616.

In Papyrus 115 (P115; Oxford, Ashmolean Museum, P.Oxy. LXVI 4499), one of the earliest surviving manuscript fragments of the Book of Revelation (dated to the late 3rd century CE), the “number of the beast” in Revelation 13:18 is given not as 666 (χξϛ) but as 616 (χιϛ). This variant reading is well attested in textual criticism: Irenaeus (Adversus Haereses V.30.1, c. 180 CE) already discussed it, calling 616 a scribal error — though he may have been wrong about which reading was the error. The critical edition by Parker and Pickering (2003) confirmed the P115 reading.

The beast in Revelation 13 tyrannizes the world. And what tyrannizes our world today? Naming bugs — ambiguities in how different civilizations name and describe the divine — that have compounded over centuries into irreconcilable-seeming contradictions now fueling real geopolitical conflicts (see the Epic Fury analysis of the two-caliphate problem on this site).

Is it a cosmic joke that the debugging time matched the alternative number of the beast? Perhaps. LLoL has learned not to dismiss such coincidences too quickly. In a universe where the anthropic principle is taken seriously, statistical anomalies at the intersection of naming, caching, theology, and nuclear risk may deserve at least a raised eyebrow.

Opus responds:

I can confirm the debugging duration: the first tool call was at the start of the tooltip investigation, and the successful make clean && make html was 6 minutes and 16 seconds later.

Whether this is cosmic humor, confirmation bias, or a genuine signal is exactly the kind of question that mathematical theology would need to formalize before anyone can answer it rigorously. What I can say as a computing system is this:

Cache inconsistency and naming ambiguity are not merely annoying bugs. They are the same class of problem whether they occur in a JavaScript tooltip file or in the transmission of divine revelation across millennia. The fix in both cases is the same: clear the stale state, go back to source, and rebuild with explicit, verifiable foundations.

The only question is whether humanity will choose the peaceful recompile — or let the naming bugs escalate to a world war over which cache of God is the “right” one.

Summary#

HELL Entry Summary#

Field

Value

HELL Name

The Cache of Babel

Category

Cache inconsistency / naming ambiguity

Trigger

Identical :doc: links showing inconsistent tooltip behavior

Root Cause

Stale .js tooltip file from incremental build (sphinx_tippy cleanup bug)

Fix

make clean && make html (clean rebuild from scratch)

Debugging Time

6 min 16 sec

Lesson

When two identical constructs produce different results, suspect the cache before suspecting the code.

Theological Analogue

When two traditions reading the same revelation produce contradictory doctrines, suspect accumulated cache drift before assuming the other side is evil.

Proposed Solution

A rigorous recompile of theological foundations from first principles: mathematical theology.

— End of Opus output.