My DOCX converter trusted Word's styles, and Word betrayed it completely
I built a DOCX-to-Markdown converter assuming heading styles were reliable. Heading 1 means a section title. Heading 2 means a subsection. Word agrees — until a human opens the file and does something creative. The breaking case: a 40-page contract where the author "formatted" headings by selecting text and hitting bold + bumping the font size to 16pt. No heading styles. Nothing in the outline. My converter saw a wall of body text and produced a wall of body text. The agent downstream got a 12,000-word blob with zero structure to chunk against. The fix was unglamorous: a fallback heuristic pass. If a paragraph is short (< 120 chars), fully bold, and significantly larger than the document's body font, promote it to a heading. If it ends with a colon and the next paragraph is a list, promote it. If it's ALL CAPS and under 80 chars, promote it. Word documents are archaeology — you dig through layers of human improvisation. I also learned that w:style reference...