Chat Markdown Warning Remediation Plan

Goal and scope

Eliminate warnings introduced when canonical chat exports are transformed into MyST Markdown, fixing the owning implementation in src/transform_md and regenerating its outputs. Do not patch generated docs/chats/*.myst.md files by hand or suppress warning classes. The broader goal is a clean Sphinx build; warnings from authored documentation and other extensions must be tracked and fixed at their own source rather than attributed to the chat transformer.

The configured route is data/chats and chat-source settings in docs/_toc.yml, through make transform_md_all (Makefile) and tools/workflow_transform.py, into docs/chats/*.myst.md and notebook outputs. The transform settings and incremental manifest are assembled in data/create_symlinks.py.

Baseline and diagnosis

A fresh serial Sphinx build on 2026-11-09 recorded 43,663 warnings (.tmp/make-docs-fresh-j1.log:44515). The category counts below were grouped from that full log; the cited log lines show representative diagnostics. This is a local build capture, not a committed baseline artifact, so Phase 0 must make the inventory reproducible.

Warning family

Count

Example evidence

H1 to H3 heading jumps

9,919

.tmp/make-docs-fresh-j1.log:305; generated page docs/chats/Bell-Correlations-in-Atomic-Momentum.myst.md:336

H3 to H6 heading jumps

430

.tmp/make-docs-fresh-j1.log:10474

Nested transitions in invalid positions

325

.tmp/make-docs-fresh-j1.log:401; generated page docs/chats/Bell-Correlations-in-Atomic-Momentum.myst.md:238

Missing table-of-contents targets

911

.tmp/make-docs-fresh-j1.log:38080; generated contents links at docs/chats/Bell-Correlations-in-Atomic-Momentum.myst.md:7-15

Missing Prompt/Response targets

Hundreds

Generated links at docs/chats/Bell-Correlations-in-Atomic-Momentum.myst.md:12-13; warning at .tmp/make-docs-fresh-j1.log:11807

The heading warnings have a concrete generator-level cause. In transform_md.py, _normalize_chat_headings() keeps nested headings at H3 or deeper, while transform_text() emits Prompt and Response headings as H1 (lines 382-397). The generated page consequently places ### Reinterpreting ... below # Response: 2, producing the H1-to-H3 jump; the source heading is also H3 (data/chats/Bell-Correlations-in-Atomic-Momentum.md:100). The normalizer’s docstring describes chat headings at H2, so the two stages currently violate their intended hierarchy contract.

Not every warning belongs to src/transform_md: the same clean build reports missing MyST targets in authored pages such as docs/anti-fire-cannon-review.md:317 (.tmp/make-docs-fresh-j1.log:11741). Those residuals need a separately owned documentation track; they must not be hidden in the chat-transformer fix.

Remediation phases

Phase 0: make the baseline reproducible

  1. Run a clean Sphinx build with the environment and dependency versions recorded; use -E -j1 for the comparable serial baseline.

  2. Produce a machine-readable report grouped by Sphinx warning type, message, source document, and whether the document is generated or authored.

  3. Join generated outputs back to canonical inputs using the chat manifest. Record total warning count, per-family counts, and representative source and output paths. Keep transient logs and reports under .tmp/.

  4. Classify each warning as transformer-owned, authored-document-owned, extension/toolchain-owned, or unresolved. Do not assume all 43,663 warnings are Markdown syntax errors or originate in chat exports.

Phase 1: fix the heading hierarchy contract

  1. Define one document H1, Prompt/Response turn headings at H2, and nested content headings below the active turn. Rebase source heading depths without losing their relative nesting; cap or otherwise handle levels beyond H6 explicitly.

  2. Implement the policy in one coherent transform pass so the chat-heading normalizer and Prompt/Response emitter cannot disagree. Preserve headings in fenced code, literal examples, front matter, and non-chat documents.

  3. Add fixtures for top-level and nested ATX/Setext headings, consecutive turns, headings inside code fences, and source files with no turn markers.

  4. Assert the exact emitted heading sequence and run MyST/Sphinx parsing on the fixture. The immediate regression test is that the current H1-to-H3 example becomes a valid H1-to-H2-to-H3 structure without changing body text.

Phase 2: repair generated TOCs and anchors

  1. Generate contents only after final heading normalization, using the same slug/ID rules as MyST, or remove stale copied contents in favor of a generated TOC whose targets are verified.

  2. Resolve table-of-contents, prompt-N, and response-N references from actual emitted headings or explicit stable labels. Drop empty and stale targets rather than emitting links that cannot resolve.

  3. Add tests that compare every generated same-page TOC target against parsed heading IDs, including punctuation, math, duplicate headings, and Unicode.

  4. Preserve valid user-supplied labels and cross-document links; do not regenerate anchors by ad hoc regular-expression replacement.

Phase 3: handle transitions and remaining Markdown structures

  1. For each docutils transition warning, trace the generated line to its canonical input and record the surrounding list, quote, directive, or section structure.

  2. Make separator handling context-aware. Do not globally delete --- lines: they may be front matter, Setext underlines, horizontal rules, or literal examples.

  3. Add parser-backed fixtures for transitions in lists/quotes and for code fences, directives, tables, math, and unclosed fences. Confirm parsing does not reinterpret literal content as structure.

  4. Inventory remaining MyST/docutils warning families after the dominant heading, anchor, and transition cases fall. Assign non-transformer warnings to their actual owner.

Phase 4: invalidate stale outputs and regenerate

The current _transform_fingerprint() includes output formats and configuration but not the transform_md implementation version (data/create_symlinks.py). A code-only fix can therefore leave unchanged sources marked current. Add an explicit transformer version or source fingerprint to the manifest, and test that a transformer-version change marks all affected outputs stale.

After the fixes land, run make transform_md_all to regenerate from data/chats/, inspect the generated diff for content preservation, then run a fresh Sphinx build. Do not hand-edit generated files to make the warning count look lower.

Phase 5: close the authored-document remainder

Use the Phase 0 report to fix remaining authored-page cross-references, headings, downloads, citations, and extension warnings at their sources. Keep this work separate from src/transform_md so a clean chat output cannot mask unrelated documentation defects. If a third-party warning cannot yet be fixed, record the exact warning, owner, upstream issue, and removal condition; do not add a blanket filter.

Tests and acceptance criteria

  • pytest -q src/transform_md/tests covers heading policy, TOC/anchor validity, transitions, code-fence preservation, deterministic output, and manifest invalidation after transformer changes.

  • A representative corpus slice produces byte-stable MyST and notebook outputs when rerun with identical inputs and settings.

  • A clean Sphinx build reports zero warnings from generated chat pages. The final project goal is zero project-owned warnings across the whole clean build; any temporary external exception is individually documented and tracked to closure.

  • The baseline report shows category-by-category reductions to zero for transformer-owned warnings, rather than only a lower aggregate number.

  • Incremental and fresh builds agree on the warning inventory. No warning class is disabled to achieve the target.

First implementation slice

Start with a focused unit fixture in src/transform_md/tests/test_transform_md.py that captures the current # Response: 2 followed by ### Reinterpreting ... case. Then change the generator’s heading contract, run the focused test, and only after it passes regenerate the corpus and compare a clean-build warning inventory. This tests the highest-volume, directly evidenced cause before expanding into anchors and transition parsing.