DOCX Diff Comment

Docx Diff & Comment

Description

This skill compares two versions of a Word document (V1 and V2), identifies new features added in V2, adds Word comments (annotations) to the V2 document at each new feature location, and generates a standalone requirements table sorted by development effort (person-days).

Prerequisites

The following tools are required:

• pandoc: Convert docx to markdown for text extraction and comparison
• python-docx: Generate the requirements table as a Word document
• docx unpack/pack utilities: Helper scripts (unpack.py, comment.py, pack.py, sanitize.py) to manipulate the OOXML structure of docx files (these scripts are typically available in docx-processing toolkits)

Usage Scenario

• Comparing two versions of a requirements document or project plan
• Annotating new features in a revised document
• Generating a development effort estimation table for new requirements

Instructions

Step 1: Extract Text & Compare

1. Use pandoc to convert both docx files to markdown:

   pandoc v1.docx -o v1_content.md
   pandoc v2.docx -o v2_content.md
   

2. Read both md files, compare paragraph by paragraph, identify new features, chapters, and sub-modules in V2
3. For each new item, record: feature name, module, description

Step 2: Add Comments to V2 Document

1. Unpack V2 docx:

   python scripts/unpack.py v2.docx v2_unpacked/
   

2. Read v2_unpacked/word/document.xml, locate the <w:r>...</w:r> block containing each new feature text
3. Create comments using comment.py. Use a consistent comment template and author:

   python scripts/comment.py v2_unpacked/ <comment_id> "V2 new feature: <module> / <feature>. Not present in V1, added in V2."
   

   • Comment author should be set to "AI Assistant"
   • comment_id starts from 0 and increments for each new feature
4. Insert comment markers into document.xml:
   • Before the target <w:r>: <w:commentRangeStart w:id="N"/>
   • After </w:r>: <w:commentRangeEnd w:id="N"/><w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="N"/></w:r>
   • Markers must be direct children of <w:p>, never inside <w:r>
   • Insert from the end backward to avoid position offset
5. Pack the annotated document:

   python scripts/pack.py v2_unpacked/ v2_annotated.docx --original v2.docx
   

6. Run sanitize.py to clean up any malformed XML or orphaned comment references

Step 3: Generate Requirements Table

Use python-docx to generate a Word table with these columns:

Append summary row with total feature count and total person-days.

Effort Estimation Reference

The following table provides reference effort ranges for common feature types. Final estimates should be adjusted based on actual complexity, team size, and technology stack.

Note: These are reference values only. Always document assumptions in the table footer.

Notes

1. Comparison scope: Focus on structural differences — new modules, sub-features, chapters. Ignore wording tweaks, typo fixes, and formatting changes.
2. Cleanup: Delete temporary files (.md, unpacked directories) after completion. Only keep the final deliverables.
3. Deliverable naming convention:
   • {DocumentName}_V2_with_comments.docx — Annotated V2 document with all new features highlighted
   • V2_New_Requirements_Table.docx — Requirements table sorted by effort (person-days), with summary row
4. Batch comment insertion: When inserting multiple comment markers in document.xml, always process from the end of the file backward to avoid position offsets.

Examples

Input

User provides two docx files:

• Platform_V1.docx (old version)
• Platform_V2.docx (new version)

Output

1. Platform_V2_annotated.docx — V2 document with comments on all new features
2. V2_new_requirements_table.docx — Requirements table sorted by effort, e.g.: