document-comparison

Overview

Compares two documents (DOCX, PDF, Markdown, or plain text) and produces a visual side-by-side diff and/or a structured change summary. Identifies additions, deletions, modifications, and moved content. Useful for reviewing contract changes, policy updates, or document revisions.

Workflow

<Workflow - Compare description="Load two documents, compute differences, generate summary and/or visual diff, and present results." tools=[file_read_docx, file_read_pdf, file_read, run_python, file_write, open_in_session_tab] triggers=["compare these docs", "what changed between versions", "diff these files", "document comparison", "show differences between"]

1. [Decide] Determine file types of {{file_a}} and {{file_b}} by extension.

   • .docx: use file_read_docx
   • .pdf: use file_read_pdf
   • .md, .txt, or other text: use file_read
   • Unsupported extension: [Ask user] "That file type isn't supported. I can compare DOCX, PDF, Markdown, and plain text files."

2. [Agent] Load both documents using the appropriate reader from step 1. Validate: Both files return non-empty text content. If fails: Report which file could not be read and the error. Ask user to confirm the path.

3. [Decide] Are documents identical?

   • Yes: Inform user: "These documents are identical. No differences found." Stop.
   • No: Continue.

4. [Decide] Are documents excessively large (either file over 50,000 characters)?

   • Yes: [Ask user] "These are large documents ([X] and [Y] characters). Comparison may take a moment. Want me to proceed with the full comparison, or compare a specific section range?"
   • No: Continue.

5. [Agent] Compute differences using run_python with difflib.SequenceMatcher.

   • Split documents into paragraphs (double newline or heading boundaries).
   • Compare at paragraph level to identify added, removed, modified, and moved sections.
   • For modified paragraphs, run word-level diff to identify inline changes. Validate: Diff data structure produced with at least one of: additions, deletions, modifications. If fails: Fall back to simple line-by-line comparison.

6. [Decide] Check diff noise level. Is over 80% of content flagged as changed?

   • Yes: [Ask user] "These documents have very different structures. Over 80% of the content differs. The comparison will be noisy. Want me to proceed anyway, or would a high-level summary be more useful?"
   • No: Continue.

7. [Decide] What output does the user want (based on {{output_format}})?

   • "markdown" or "both": Continue to step 8.
   • "html" only: Skip to step 9.

8. [Agent] Generate a structured change summary in Markdown. Write to workspace as comparison_summary.md. Format per <Template - Change Summary>. Present the summary to the user immediately. Validate: Summary file is written and contains at least the Overview and Key Changes sections.

9. [Decide] Does the user want HTML output?

   • {{output_format}} is "html" or "both": Continue to step 10.
   • "markdown" only: Skip to step 11.

10. [Agent] Generate an HTML visual diff with side-by-side layout. Use the html_design skill tokens for styling. Write to workspace as comparison_diff.html. Features: side-by-side panels, green highlights (additions), red highlights (deletions), yellow highlights (modifications), line numbers, jump-to-change navigation, summary stats header. Validate: HTML file written and contains diff content.

11. [Agent] Open the generated file(s) in session tabs using open_in_session_tab.

    • If both formats: open summary first, then HTML diff.
    • If single format: open that file.

</Workflow - Compare>

<Template - Change Summary>

Document Comparison Summary

File A (baseline): [filename] File B (revised): [filename] Date: [comparison date]

Overview

• Sections added: X
• Sections removed: X
• Sections modified: X
• Overall change magnitude: [Minor / Moderate / Significant / Major]

Key Changes

1. [Most significant change in plain language]
2. [Second most significant]
3. ...

Detailed Changes

Added

• [New content summary]

Removed

• [Removed content summary]

Modified

• [Section name]: [what changed]