agent's markdown-to-comments conversion broke the latex, broken output, render failed

TL;DR

Converting markdown cells to code comments by prefixing # leaves LaTeX like $\alpha$ as unreadable comment noise (and the backslashes can trip tooling). Translate math into plain words during conversion: 'alpha: the learning rate' instead of the raw expression. The converted script's comments should read as explanations, not as markup leaking through.

agent's markdown-to-comments conversion broke the latex, broken output, render failed

Use this when

• Converted scripts have comments full of raw LaTeX.
• Readers cannot understand the converted comments.
• The agent converts markdown mechanically.

Not for this skill when

• The conversion crashes. That is an exporter bug.
• LaTeX is fine in the notebook. This is only about conversion.

Steps

1. Find the LaTeX in the converted comments. Verify: you see the raw markup.
2. Change the converter: detect math spans and render their meaning in words. Verify: comments read as plain language.
3. For simple symbols, use unicode or words (alpha, sigma, ~). Verify: no backslash sequences remain.
4. For complex equations, summarize the equation's role in one line. Verify: a reader gets the point without the math.
5. Review the converted script cold. Verify: comments explain, not confuse.

Variant phrasings

markdown latex to comments conversion

Short form. Words, not markup.

latex broken in converted script

The symptom phrasing. Translate the math.

notebook convert comments math

General phrasing. Meaning over markup.

Compatibility: Any markdown-to-comment converter. The principle is format-agnostic.

Why it happens

LaTeX is a rendering language: $\alpha$ means nothing until typeset. In a code comment there is no typesetter, so the raw markup is worse than useless; it is confusing, and backslash sequences can trip linters and privacy scanners. The comment's job is to explain, and the explanation of math is words about what the math means in this code.

Edge cases / pitfalls

• Do not just strip the LaTeX; that deletes meaning. Translate it.
• Keep it brief: one line per equation. Comments are not textbooks.
• If the math is the point (a formula being implemented), put the formula in the docstring as plain text and explain the terms.
• Test the converter on a math-heavy notebook. Edge cases cluster there.
• When the same equation appears in several cells, translate it once and reference the first translation.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_QwWjSixP0S7bEHEtmyHFzA