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 |
|
H3 to H6 heading jumps |
430 |
|
Nested transitions in invalid positions |
325 |
|
Missing |
911 |
|
Missing Prompt/Response targets |
Hundreds |
Generated links at |
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¶
Run a clean Sphinx build with the environment and dependency versions recorded; use
-E -j1for the comparable serial baseline.Produce a machine-readable report grouped by Sphinx warning type, message, source document, and whether the document is generated or authored.
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/.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¶
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.
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.
Add fixtures for top-level and nested ATX/Setext headings, consecutive turns, headings inside code fences, and source files with no turn markers.
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¶
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.
Resolve
table-of-contents,prompt-N, andresponse-Nreferences from actual emitted headings or explicit stable labels. Drop empty and stale targets rather than emitting links that cannot resolve.Add tests that compare every generated same-page TOC target against parsed heading IDs, including punctuation, math, duplicate headings, and Unicode.
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¶
For each
docutilstransition warning, trace the generated line to its canonical input and record the surrounding list, quote, directive, or section structure.Make separator handling context-aware. Do not globally delete
---lines: they may be front matter, Setext underlines, horizontal rules, or literal examples.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.
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.
Tests and acceptance criteria¶
pytest -q src/transform_md/testscovers 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.