# 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 ```xml ``` ### Comment Body Example ```xml Comment text line 1 Comment text line 2 ``` 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: ```xml ``` ## Content Types `[Content_Types].xml` must include: ```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.

zh-xx

contract-review