version comparison broke - v2 was a .docx and v3 was a PDF, and the agent's text extraction produced different line...

TL;DR: Convert both versions to the same format through the same extraction pipeline before diffing, so line breaks, spacing, and encoding are identical except for real edits. The agent was comparing docx-extracted text against PDF-extracted text, and the two extractors disagree on line breaks even when the words are identical.

version comparison broke  -  v2 was a .docx and v3 was a PDF, and the agent's text extraction produced different line breaks so nothing aligned

1. Confirm the format mismatch is the cause. Extract text from both files with their current pipelines and diff a section you know is unchanged. Expected: the unchanged section shows heavy diff noise (line-break and spacing differences), proving the extractors disagree.

1. Pick one canonical path and route both versions through it. Either convert the docx to PDF and extract both as PDF text, or extract the docx natively and render the PDF to the same plain-text flow. The rule is one pipeline for both inputs, not the best pipeline for each. Expected: the known-unchanged section now diffs clean.

1. Normalize before diffing. After extraction, apply the same normalization to both texts: unify line endings, collapse whitespace runs, and normalize quotes and dashes. Expected: the only remaining diffs are word-level edits the counterparty actually made.

1. Re-run the version comparison and spot-check. Pick three known edits and three known-unchanged sections, and verify the diff flags exactly the edits. Expected: the diff is short, readable, and every flagged change is real.

1. Record the extraction path with the diff output. Every comparison result should note which pipeline produced it ("both via PDF text extraction"). Expected: a future mismatch is diagnosable from the output metadata instead of looking like a mysterious full-document rewrite.

Use this when

• comparing a .docx against a PDF reports the whole document as changed
• the diff is dominated by line-break, spacing, or pagination noise
• the two versions took different extraction paths (different libraries or different conversions)
• a "no real changes" version pair produces a huge diff

Not for this skill when

• both versions are the same format and the diff is still noisy (check OCR noise or reflow handling instead)
• the diff is clean but the agent misreads the changes (check the summarizer, not the extractor)
• one of the files is corrupt or password-protected (fix file access first)

Variant phrasings

• docx vs PDF comparison flagged everything because of line break differences
• version diff broke on mixed file formats
• agent compared Word and PDF versions and nothing aligned
• text extraction differed between formats so the diff was all noise

Why it happens

Docx stores text as styled runs in XML with explicit paragraph breaks; PDF stores positioned glyphs with no notion of paragraphs at all. Two different extractors reconstruct "lines" using different heuristics, so identical wording comes out with different breaks. A diff tool sees different line breaks as different content, and the real edits drown in formatting noise.

Edge cases

• Converting docx to PDF reflows pagination, which can shift page-referenced citations. Normalize text for the diff, but keep the original files for page-accurate citations.
• Scanned PDFs need OCR first, which adds a third extraction behavior. OCR both versions if either is scanned, even if one is born-digital.
• Tracked-changes docx files carry deleted text in the XML. Accept or reject revisions before extraction, or the deleted runs will pollute the canonical text.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_31ygNh-lMgXNPwKazcx7Ig