/contract-review

OOXML Notes for Comment-Only Reviews

This reference documents the minimal OOXML pieces needed by this skill. It is intentionally lightweight and focused on comment insertion only.

Scope

• Supported: Adding Word comments to an existing .docx without changing document text.
• Not supported: Tracked changes, rich styling, or full schema validation.
• Validation: Only file presence + XML well-formedness.

Required Files

The comment workflow touches only these parts inside a .docx package:

• word/document.xml (the main body)
• word/comments.xml (comment bodies)
• word/_rels/document.xml.rels (relationship to comments.xml)
• [Content_Types].xml (content type override for comments.xml)

Namespaces

Use the WordprocessingML namespace for comment elements:

• w = http://schemas.openxmlformats.org/wordprocessingml/2006/main

Comment Injection Model

To add a comment:

1. Insert a w:commentRangeStart element before the target paragraph content.
2. Insert a w:commentRangeEnd element at the end of the paragraph.
3. Insert a w:commentReference run right after the range end.
4. Append a w:comment entry in word/comments.xml.
5. Ensure document.xml.rels and [Content_Types].xml include the comments part.

Range Markup Example

<w:commentRangeStart w:id="12"/>
<!-- paragraph content -->
<w:commentRangeEnd w:id="12"/>
<w:r><w:commentReference w:id="12"/></w:r>

Comment Body Example

<w:comment w:id="12" w:author="Reviewer" w:initials="RV" w:date="2025-01-10T12:00:00Z">
  <w:p><w:r><w:t>Comment text line 1</w:t></w:r></w:p>
  <w:p><w:r><w:t>Comment text line 2</w:t></w:r></w:p>
</w:comment>

If a w:t node begins or ends with whitespace, add xml:space="preserve" so Word preserves spacing.

Relationships

word/_rels/document.xml.rels must reference the comments part:

<Relationship Id="rIdX"
  Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments"
  Target="comments.xml"/>

Content Types

[Content_Types].xml must include:

<Override PartName="/word/comments.xml"
  ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml"/>

Common Failure Modes

• Comments do not show up: missing relationship or content type override.
• Comments show but are empty: comments.xml malformed or w:t missing text node.
• Spaces missing: add xml:space="preserve" on the w:t nodes.

When to Extend

If you need tracked changes, comment replies, or advanced metadata (e.g., commentsExtended), add separate modules and document them here. Keep this file short and only include what this skill actually uses.