Skip to content
Skills Library
Management & product · Analysis

docx-diff-comment

/docx-diff-comment

Compare two Word documents to find new features in V2, add comments to the V2 document for each new feature, and generate a requirements table with effort estimation in person-days. Invoke when user asks to compare two docx documents, add comments for new features, or generate a requirements diff table.

Repository
trae-skills ↗
Licence
MIT
Last repository change
10.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 10.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Compare two Word documents to find new features in V2, add comments to the V2 document for each new feature, and generate a requirements table with effort estimation in person-days. Invoke when user asks to compare two docx documents, add comments for new features, or generate a requirements diff table.

Original author description

Compare two Word documents to find new features in V2, add comments to the V2 document for each new feature, and generate a requirements table with effort estimation in person-days. Invoke when user asks to compare two docx documents, add comments for new features, or generate a requirements diff table.

How it works

  1. Description
  2. Prerequisites
  3. Usage Scenario
  4. Instructions
  5. Effort Estimation Reference
  6. Notes
  7. Examples
Original SKILL.md headings · 115 lines, 789 words
SKILL.md preview
---
name: docx-diff-comment
description: Compare two Word documents to find new features in V2, add comments to the V2 document for each new feature, and generate a requirements table with effort estimation in person-days. Invoke when user asks to compare two docx documents, add comments for new features, or generate a requirements diff table.
---

# 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:

| Column | Description |
|--------|-------------|
| No. | Sorted by effort descending |
| Feature Name | Name of the new feature |
| Module | Functional module |
| Description | Brief description |
| Development Content | Specific dev work |
| Effort (person-days) | Estimated days |

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.

| Feature Type | Reference Range (person-days) | Description | Example |
|-------------|------------------------------|-------------|---------|
| Brand-new independent module (with algorithm/model) | 6–10 | Module introduces new technical capability; may involve ML/NLP components | AI measurement, NLP parsing, rule engine |
| Visualization component integration | 4–6 | Integrate third-party or self-built visualization widgets | GIS map dashboard, chart library, data timeline |
| Interactive feature development | 3–5 | New user interactions on existing pages | Area selection query, layer toggle, drag-and-drop |
| Data storage / export enhancement | 2–3 | Extend existing data workflows | Save & download, Excel export, file upload |
| Statistics / classification function | 1–2 | Add or refine counting/categorical logic | Project status statistics, report breakdown by dimension |
| Documentation / process design | 1 | Non-code work items | API doc writing, mechanism design, acceptance plan |

> **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.:

| No. | Feature | Module | Effort (days) |
|-----|---------|--------|---------------|
| 1 | AI Calculation | Investment | 8 |
| 2 | Map Visualization | Dashboard | 5 |
| 3 | Infrastructure Dashboard | Dashboard | 5 |
| ... | ... | ... | ... |
| Total | | | 34 |

Versions

The database has no other skills named docx-diff-comment.

Database snapshot: 13.11.2026 · package version 2bf452cecef1 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95Docx
    Word document processing. USE WHEN docx, Word document. SkillSearch('docx') for docs.
  • 100docx
    Use this skill whenever the user wants to create or edit .docx (Microsoft Word) files. This includes creating new Word documents from scratch, editing existing Word documents, extracting content from Word files, converting between formats, adding images or other content to Word…
  • 100docx-official
    Generating Word documents programmatically with docx library in Node.js. Use when generating .docx reports, contracts, invoices, or any structured Word document from data.
  • 100word-read-write
    Create and read Microsoft Word (.docx) documents. Use this skill when you need to generate reports/letters/templates as .docx or extract readable text from existing .docx files.
  • 100documents
    Create, read, edit, review, comment on, sanitize, render, and validate Microsoft Word DOCX documents. Use whenever a DOCX or Word document is a primary input or deliverable, including reports, proposals, forms, templates, tracked revisions, comments, tables, images, headers,…
  • 100microsoft-word
    Create, edit, and manipulate Word documents (.docx) programmatically. Use when someone asks to "generate a Word document", "create a report in docx", "mail merge", "fill Word template", "extract text from Word", "convert markdown to Word", "add tables to Word", or "automate…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.