agent's diff counted 60 changes but 58 were comment balloons the counterparty left in the margin that the parser read...

TL;DR

The parser read the counterparty's margin comment balloons as body text, so 58 of 60 'changes' were just comments. Extract annotations and comments separately from the body (docx comments part, PDF annotations), diff the body text only, and report the comments as their own list for reviewers.

The symptom

agent's diff counted 60 changes but 58 were comment balloons the counterparty left in the margin that the parser read as body text

Steps

1. Extract comments separately from body text

For docx, read the comments part and the comment-range markers; for PDF, read the annotation objects. Build two streams: body text and comment text. Never let them mix. Expected: 58 comment texts in the comment stream, body text clean.

2. Diff body text only

Run the comparison on the body stream. The two real edits surface; the comment balloons contribute zero changes. Expected: Diff count drops from 60 to the real number of text edits.

3. Report comments as their own list

Present the comments separately: author, quoted context, and comment text. Reviewers need them, just not counted as redlines. Expected: A comment digest alongside (not inside) the redline report.

4. Guard the parser

Add a pipeline rule: comment/annotation content is never body text. Any future parser change must preserve the two-stream split. Expected: A parser upgrade cannot silently re-merge the streams.

When to use

• Most reported changes are margin comments, not edits
• The parser output contains comment text inline with clauses
• Change counts are an order of magnitude above the plausible edit count

When not to use

• The comments were converted to tracked changes (then they are real edits)
• The document format has no comment layer (the text came from somewhere else)
• You actually want comments diffed (rare; say so explicitly)

Why it happens

Naive text extraction flattens everything on the page into one string, including comment balloons, annotation popups, and margin notes. The diff then treats each comment as inserted body text. Structured extraction keeps the annotation layer separate, which is also where it belongs for review.

Edge cases

• Resolved vs open comments: filter to open ones for the review digest.
• Comments anchored to deleted text: keep the anchor context so the comment still makes sense.
• PDF sticky notes with no visible balloon: they still extract as annotations; check the annotation list.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_7fJotJunMO-oOdMBse58cg