Document Conversion Guide

Every format conversion is a negotiation about what survives. This skill plans and executes document conversions — word-processor files to markdown, markdown to PDF, spreadsheets to CSV, slide decks to handout documents — by naming what is at risk before converting anything, choosing the shortest reliable pipeline, and verifying the result against a checklist instead of a glance.

When to use this skill

• A document must move between an editable format and a page-layout or plain-text format
• A pile of legacy files needs migrating to a wiki, a docs site, or an archive format
• Tables, footnotes, tracked changes, or embedded images make a conversion feel risky
• Spreadsheet data must become CSV for an import, or structured text must become a spreadsheet
• A conversion already happened and something about the output looks quietly wrong
• A team is choosing a canonical format for long-term archiving or collaborative editing

Workflow

1. Establish three things up front: the source format, the target format, and the document's job after conversion — archival copy, further editing, publishing, or data import. The job decides how much loss is tolerable and where.
2. Inventory the at-risk features before touching anything. The usual casualties: tracked changes and comments, footnotes and endnotes, cross-references, merged table cells, embedded fonts, headers and footers, image alt text, numbered lists that restart, and spreadsheet formulas — which flatten into values. List which of these the source actually uses.
3. Decide the fate of each at-risk feature — preserved, deliberately flattened, or dropped — and confirm with the user wherever the answer is not obvious. "Comments will be lost" is a decision someone should get to make, not something they discover later.
4. Choose the shortest pipeline that covers the feature list. A direct conversion beats a chained one: every intermediate format is another chance to lose something silently.
5. On a batch job, convert one representative document first — the one with the worst tables and the most footnotes — and verify it end to end before running the rest.
6. Verify with the checklist below, against the source document, not against memory.
7. Deliver the output with a short loss report: what changed, what was flattened by design, and what needs manual attention.

Verification checklist

• Heading levels survived and nest correctly — no body text promoted, no skipped levels
• Tables: row and column counts match the source; merged cells reviewed by eye
• Images present, positioned sensibly, alt text retained where the target supports it
• Footnotes and endnotes still linked to their anchors, not orphaned at the bottom
• Internal cross-references and external links resolve
• Special characters, symbols, and non-Latin scripts intact
• Numbered lists keep their numbering; nested lists keep their depth
• Headers, footers, and page numbers handled per the target's conventions, not dropped blind
• Metadata that matters (title, author, language) carried over or deliberately stripped
• Word count within a few percent of the source — larger drift means dropped content

Guardrails

• Never promise a lossless round trip between editable and page-layout formats. State what will degrade, and state it before converting rather than after.
• Never convert the only copy in place. The source file stays untouched no matter what happens.
• Spreadsheet to CSV means formulas freeze into values and each file holds one sheet — say so before doing it, not after the import fails downstream.
• Documents headed for legal, regulatory, or contractual use get a PDF target and a recommendation for page-by-page human review; automation does not sign off on those.
• When the target lacks a feature the source uses (footnotes, say), propose the convention — inline brackets, an endnote section — instead of letting the converter improvise.