agent's notebook-to-script conversion failed: dropped all markdown context, broken docs

TL;DR

The default script exporter drops markdown cells, so the converted script loses every explanation, leaving bare code that nobody can review. Make the agent convert markdown cells into comments (or a module docstring for the opening narrative) during conversion. The script should read like the notebook: narrative above the code it explains. Reviewability is the whole point of the conversion, and context-free code fails it.

agent's notebook-to-script conversion failed: dropped all markdown context, broken docs

Use this when

• Converted scripts contain code but no explanations.
• Reviewers cannot understand the converted script without the notebook.
• An agent converts notebooks to scripts for handoff or CI.

Not for this skill when

• The conversion crashes. That is an exporter error.
• The script runs but is wrong. That is a logic issue.

Steps

1. Inspect the current conversion output. Verify: markdown is indeed absent.
2. Change the agent's conversion to emit markdown cells as # comments (headings as section comments). Verify: the script reads top to bottom with narrative.
3. Promote the opening markdown to a module docstring. Verify: help() on the module shows the overview.
4. Convert markdown code fences and math to plain-text comments (no LaTeX). Verify: the script has no leftover markup.
5. Have a human review the converted script cold. Verify: they can follow it without the notebook.

Variant phrasings

nbconvert script lost markdown

Short form. Emit markdown as comments.

notebook to script no comments

The review phrasing. Context is the deliverable.

agent convert notebook script docs

The agent phrasing. Narrative above code.

Compatibility: nbconvert 6/7 script exporter, or agent-side conversion. The markdown-to-comment mapping is custom logic.

Why it happens

The script exporter's default (code only) assumes the consumer wants runnable code, but handoff and CI consumers want understanding. Notebooks put the why in markdown and the what in code; dropping the markdown keeps the what and deletes the why. An agent doing the conversion must be told that documentation preservation is a requirement, because the default tool does the opposite.

Edge cases / pitfalls

• LaTeX in markdown does not survive as comments usefully. Render the meaning in plain words.
• Very long markdown cells become comment walls. Summarize rather than transcribing verbatim.
• Keep the cell order: narrative must stay above the code it describes.
• The converted script still needs the notebook's implicit order guarantees made explicit (imports first).

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_-2RMtyRXU4CyAbIGBI2c5Q