DOCX Annotated Review

Annotated Word Document Review

Overview

This skill takes a user-provided Word document (.docx) and produces an annotated review copy with color-coded highlights and margin comments. The output preserves the original text while visually marking issues and suggestions directly in the document, similar to a professor's markup or editor's review.

The core workflow is: unpack original .docx → analyze content → apply color highlights + typo corrections + comments in XML → repack into annotated .docx.

Prerequisites

Read the base docx skill first:

Read /mnt/skills/public/docx/SKILL.md

This skill extends the "Editing Existing Documents" workflow from the docx skill (unpack → edit XML → repack). All XML editing rules, comment.py usage, and pack/unpack tooling from that skill apply here.

Annotation System

Color Highlight Legend

Typo/Error Corrections

For spelling or grammatical errors, apply inline corrections directly in the text using strikethrough + red highlight for the wrong text, followed by red-colored correction text in brackets.

Margin Comments

Every highlighted section should have an accompanying comment explaining the rationale and providing specific suggestions. Comments use structured labels:

• 【修改建议】 — Suggestion for revision (paired with yellow/red highlights)
• 【删减建议】 — Suggestion for deletion or major cut (paired with red highlights)
• 【保留但精简】 — Keep but condense (paired with green highlights)
• 【补充建议】 — Suggestion to add content (paired with cyan/blue highlights)
• 【拼写/语法】 — Spelling or grammar correction (paired with inline typo fixes)

Step-by-Step Workflow

Step 1: Read and Analyze the Original Document

# Copy user's file to working directory
cp /mnt/user-data/uploads/<filename>.docx /home/claude/original.docx

# Extract text for analysis
pandoc /home/claude/original.docx -o /home/claude/content.md

# Unpack for XML editing
python /mnt/skills/public/docx/scripts/office/unpack.py /home/claude/original.docx /home/claude/unpacked/

Read the extracted content carefully. Identify:

1. Spelling/grammar errors — typos, subject-verb disagreement, punctuation issues
2. Content to delete or majorly revise — irrelevant, redundant, or factually wrong passages
3. Content to rework — awkward phrasing, weak logic, structural issues
4. Content to condense — good but verbose passages
5. Missing content — gaps in logic, missing transitions, needed references or context
6. Strengths — note what works well (acknowledge in comments)

Step 2: Plan the Annotations

Before editing XML, create a structured plan:

• List each annotation with: paragraph location, highlight color, comment content, any typo corrections
• Assign sequential comment IDs starting from 0
• Plan the comment text for each annotation with the appropriate label

Step 3: Insert the Legend Table

Insert a legend title paragraph and table at the very beginning of the document body (after any existing title, before the first content paragraph).

Legend title paragraph:

<w:p>
  <w:pPr>
    <w:spacing w:before="200" w:after="200"/>
  </w:pPr>
  <w:r>
    <w:rPr>
      <w:b/>
      <w:bCs/>
      <w:sz w:val="22"/>
      <w:szCs w:val="22"/>
    </w:rPr>
    <w:t>批注说明 (Annotation Legend):</w:t>
  </w:r>
</w:p>

Legend table structure:

<w:tbl>
  <w:tblPr>
    <w:tblW w:w="5000" w:type="pct"/>
    <w:tblBorders>
      <w:top w:val="single" w:sz="4" w:space="0" w:color="auto"/>
      <w:left w:val="single" w:sz="4" w:space="0" w:color="auto"/>
      <w:bottom w:val="single" w:sz="4" w:space="0" w:color="auto"/>
      <w:right w:val="single" w:sz="4" w:space="0" w:color="auto"/>
      <w:insideH w:val="single" w:sz="4" w:space="0" w:color="auto"/>
      <w:insideV w:val="single" w:sz="4" w:space="0" w:color="auto"/>
    </w:tblBorders>
    <w:tblCellMar>
      <w:left w:w="10" w:type="dxa"/>
      <w:right w:w="10" w:type="dxa"/>
    </w:tblCellMar>
    <w:tblLook w:val="04A0" w:firstRow="1" w:lastRow="0" w:firstColumn="1" w:lastColumn="0" w:noHBand="0" w:noVBand="1"/>
  </w:tblPr>
  <w:tblGrid>
    <w:gridCol w:w="1999"/>
    <w:gridCol w:w="7351"/>
  </w:tblGrid>
  <!-- Insert 5 rows here using the row template below -->
</w:tbl>

Row template — repeat for each of the 5 rows, replacing FILL_COLOR, LABEL_TEXT, and DESCRIPTION_TEXT:

<w:tr>
  <w:tblPrEx>
    <w:tblCellMar>
      <w:top w:w="0" w:type="dxa"/>
      <w:bottom w:w="0" w:type="dxa"/>
    </w:tblCellMar>
  </w:tblPrEx>
  <w:tc>
    <w:tcPr>
      <w:tcW w:w="2000" w:type="dxa"/>
      <w:shd w:val="clear" w:color="auto" w:fill="FILL_COLOR"/>
      <w:tcMar>
        <w:top w:w="80" w:type="dxa"/>
        <w:left w:w="120" w:type="dxa"/>
        <w:bottom w:w="80" w:type="dxa"/>
        <w:right w:w="120" w:type="dxa"/>
      </w:tcMar>
    </w:tcPr>
    <w:p>
      <w:r>
        <w:rPr>
          <w:b/>
          <w:bCs/>
        </w:rPr>
        <w:t>LABEL_TEXT</w:t>
      </w:r>
    </w:p>
  </w:tc>
  <w:tc>
    <w:tcPr>
      <w:tcW w:w="7360" w:type="dxa"/>
      <w:tcMar>
        <w:top w:w="80" w:type="dxa"/>
        <w:left w:w="120" w:type="dxa"/>
        <w:bottom w:w="80" w:type="dxa"/>
        <w:right w:w="120" w:type="dxa"/>
      </w:tcMar>
    </w:tcPr>
    <w:p>
      <w:r>
        <w:t>DESCRIPTION_TEXT</w:t>
      </w:r>
    </w:p>
  </w:tc>
</w:tr>

Standard row values (Chinese — default):

English row values (use when document is primarily English):

Step 4: Apply Annotations in document.xml

4a. Applying Text Highlights

Wrap target text runs with highlight formatting in <w:rPr>:

<w:r>
  <w:rPr>
    <w:highlight w:val="yellow"/>
  </w:rPr>
  <w:t>text that needs rewording</w:t>
</w:r>

To apply a highlight, you need to either:

• Add <w:highlight w:val="COLOR"/> to an existing <w:rPr>, or
• Wrap existing <w:rPr>-less runs with a new <w:rPr> containing the highlight

If the target text is part of a larger run, split the run: keep the unhighlighted portions in separate <w:r> elements and apply the highlight only to the target portion.

4b. Fixing Typos Inline

For spelling/grammar errors, apply this pattern directly in the text:

<!-- Original wrong text: strikethrough + red highlight -->
<w:r>
  <w:rPr>
    <w:strike/>
    <w:highlight w:val="red"/>
  </w:rPr>
  <w:t>wroong</w:t>
</w:r>
<!-- Correction: red text in brackets -->
<w:r>
  <w:rPr>
    <w:color w:val="FF0000"/>
  </w:rPr>
  <w:t xml:space="preserve"> [wrong] </w:t>
</w:r>

The original wrong word gets strikethrough + red highlight. The correction follows immediately in red color text wrapped in square brackets.

4c. Adding Blue "Insert New Content" Blocks

When a new paragraph needs to be inserted at a specific location, add a new <w:p> element:

<w:p>
  <w:pPr>
    <w:shd w:val="clear" w:color="auto" w:fill="E6E6FF"/>
    <w:spacing w:after="200" w:line="360" w:lineRule="auto"/>
  </w:pPr>
  <w:commentRangeStart w:id="COMMENT_ID"/>
  <w:r>
    <w:rPr>
      <w:b/>
      <w:bCs/>
      <w:color w:val="0000FF"/>
    </w:rPr>
    <w:t>【此处需要新增】</w:t>
  </w:r>
  <w:r>
    <w:t xml:space="preserve">  Brief description of what content should be added here.</w:t>
  </w:r>
  <w:commentRangeEnd w:id="COMMENT_ID"/>
  <w:r>
    <w:commentReference w:id="COMMENT_ID"/>
  </w:r>
</w:p>

Use 【此处需要新增一整段】 when an entire paragraph is needed, 【此处需要新增】 for shorter additions.

4d. Adding Comment Markers

For each highlighted section, add comment range markers wrapping the highlighted content:

<w:commentRangeStart w:id="COMMENT_ID"/>
<!-- highlighted content runs go here -->
<w:commentRangeEnd w:id="COMMENT_ID"/>
<w:r>
  <w:commentReference w:id="COMMENT_ID"/>
</w:r>

Critical rules for comment markers:

• <w:commentRangeStart> and <w:commentRangeEnd> are siblings of <w:r>, NEVER inside <w:r>
• The <w:commentReference> must be inside its own <w:r> element
• Comment IDs must be unique integers starting from 0 and incrementing sequentially

Step 5: Create Comments

Use the comment.py script from the docx skill to register each comment:

python /mnt/skills/public/docx/scripts/comment.py /home/claude/unpacked/ COMMENT_ID "Comment text here" --author "Reviewer"

Comment text structure:

1. Label (e.g., 【修改建议】, 【保留但精简】)
2. Explanation of why this section is highlighted
3. Specific suggestions for improvement (numbered or bulleted)
4. Optional: literature/reference suggestions if applicable

Since comment.py creates plain text comments, for rich formatting (bold labels) you can edit comments.xml directly after running the script to add <w:rPr><w:b/><w:bCs/></w:rPr> to the label runs.

Step 6: Pack and Validate

python /mnt/skills/public/docx/scripts/office/pack.py /home/claude/unpacked/ /home/claude/annotated_output.docx --original /home/claude/original.docx

# Validate the output
python /mnt/skills/public/docx/scripts/office/validate.py /home/claude/annotated_output.docx

# Copy to outputs
cp /home/claude/annotated_output.docx /mnt/user-data/outputs/

XML Editing Best Practices

1. Use the str_replace tool for all XML edits. Do not write Python scripts to modify the XML.
2. Preserve original formatting: When adding highlights to existing runs, keep all existing <w:rPr> properties and just add the <w:highlight> element.
3. Split runs carefully: When only part of a text needs highlighting, split the <w:r> into multiple runs, each with appropriate formatting.
4. Maintain ID uniqueness: All w:id attributes for comments, tracked changes etc. must be unique across the document.
5. Keep comment IDs sequential: Start from 0 and increment. Match IDs between comments.xml, commentsExtended.xml, commentsIds.xml, and document.xml.
6. Use smart quotes: When adding text with apostrophes or quotes, use XML entities (‘, ’, “, ”).
7. Escape XML special characters: & → &, < → <, > → >

Quality Standards

A good annotated review:

• Does NOT modify the original text (except for inline typo corrections which are visually marked)
• Uses colors consistently according to the legend
• Every highlighted section has an accompanying comment
• Comments provide actionable, specific suggestions — not vague criticism
• Acknowledges strengths where they exist
• Typo corrections are visually clear (strikethrough + red correction)
• The legend table is always present at the top of the document
• The document opens correctly in Microsoft Word, WPS Office, and LibreOffice

Language Considerations

• If the original document is in Chinese, write comments in Chinese
• If the original document is in English, write comments in English
• For mixed-language documents, match the predominant language of each section
• The legend labels (【修改建议】 etc.) are always in Chinese as they are established conventions in this annotation system
• Comment labels can be adapted if the user prefers English (e.g., [Revision Suggestion], [Keep but Condense])