Contract Review and Redlining

Produces three outputs:

1. Redlined `.docx` — original document with tracked changes (visible del/ins in Word) and margin comments explaining each change

2. Summary document — clean Word file listing all issues and recommended changes, organized by risk level

3. Brief explanation — a short message to the user describing what was changed and why

This skill builds on the docx skill. Use the docx skill's unpack.py, pack.py, and comment.py scripts.

---

Workflow

Step 1: Read the Contract

Unpack and read the full document:

python .claude/skills/docx/scripts/office/unpack.py contract.docx unpacked/

Then read unpacked/word/document.xml. Use pandoc for a cleaner text view if the XML is hard to parse:

pandoc --track-changes=all contract.docx -o contract.md

Note any existing tracked changes by other authors — you'll need to avoid conflicting with their IDs.

Step 2: Analyze the Contract

See references/analysis-framework.md for a comprehensive checklist of what to look for by contract type. Key questions:

• Lock-in: Are there auto-renewal traps, high exit penalties, or unilateral price escalation?
• Data ownership: Who owns the data? Can it be used to train AI models or sold to third parties?
• Exit rights: Can the client terminate early with reasonable terms?
• Liability: Is liability one-sided? Does SLA compensation cap out actual damages?
• Payment: Are payment terms fair? Any prepayment requirements?
• IP: Who owns work product? Who owns data insights?

Aim for 5–15 targeted changes. More than 15 starts to overwhelm the document.

Step 3: Plan Changes Before Writing Any Code

Before touching the XML, list all planned changes in a structured way:

| # | Section | Old text (short) | Change type | New text (short) | Risk level |

|---|---------|-----------------|-------------|-----------------|------------|

| C1 | §3.3 | "30 days prepayment" | del+ins | "net 30 from invoice" | Medium |

| C2 | §5.1 | "ML training" | del | — | High |

...

This planning step prevents half-applied changes and makes it easy to write assertions.

Step 4: Scan Existing Tracked Change IDs

Before assigning IDs to your changes, scan the document for existing ones to avoid collisions:

python -c "
import re
with open('unpacked/word/document.xml', encoding='utf-8') as f:
    doc = f.read()
ids = [int(x) for x in re.findall(r'w:id=\"(\d+)\"', doc)]
print('Max existing ID:', max(ids) if ids else 0)
"

Start your IDs at max_id + 1000 (e.g., if max is 8527, use 9001, 9002, ...). This leaves room for the original document's IDs to remain stable.

Step 5: Apply Redlines via Python Script

When there are 5 or more changes, use a Python script (not the Edit tool) for reliability. The Edit tool is fine for 1–3 simple edits; scripts are safer for bulk changes.

Use scripts/apply_redlines.py as your template — it handles the assertion/uniqueness pattern. Write your changes as a list of (label, old_string, new_string) tuples.

The cardinal rules of OOXML tracked changes:

NEVER put <w:del> or <w:ins> inside <w:t>.
<w:t> contains only text. Period.
<w:del> and <w:ins> are SIBLINGS of <w:r>, never children of <w:t>.

Correct structure:

<!-- Split a run to change "thirty" to "sixty" -->
<w:r><w:t xml:space="preserve">Pay within </w:t></w:r>
<w:del w:id="9001" w:author="Claude" w:date="2025-01-01T00:00:00Z">
  <w:r><w:delText xml:space="preserve">thirty</w:delText></w:r>
</w:del>
<w:ins w:id="9002" w:author="Claude" w:date="2025-01-01T00:00:00Z">
  <w:r><w:t xml:space="preserve">sixty</w:t></w:r>
</w:ins>
<w:r><w:t xml:space="preserve"> days.</w:t></w:r>

Wrong (crashes Word):

<!-- WRONG: del/ins inside w:t -->
<w:t>Pay within <w:del...>thirty</w:del><w:ins...>sixty</w:ins> days.</w:t>

Splitting a run: When your target text sits in the middle of a longer run, split the surrounding <w:r> into parts. The prefix and suffix stay as normal runs; the changed part becomes del/ins siblings:

<!-- Old: single run "Pay within thirty days of invoice." -->
<!-- New: split into prefix + del/ins + suffix -->
<w:r><w:rPr>...same rPr...</w:rPr><w:t xml:space="preserve">Pay within </w:t></w:r>
<w:del w:id="9001" w:author="Claude" w:date="...">
  <w:r><w:rPr>...same rPr...</w:rPr><w:delText>thirty</w:delText></w:r>
</w:del>
<w:ins w:id="9002" w:author="Claude" w:date="...">
  <w:r><w:rPr>...same rPr...</w:rPr><w:t>sixty</w:t></w:r>
</w:ins>
<w:r><w:rPr>...same rPr...</w:rPr><w:t xml:space="preserve"> days of invoice.</w:t></w:r>

Copy the <w:rPr> from the original run into each split piece to preserve formatting (bold, font, color).

Modifying another author's insertion: When you need to change text inside an existing <w:ins> by someone else, split their <w:ins> into multiple pieces (the unchanged parts stay inside their <w:ins>, giving them different IDs; your changes go between them):

<!-- Original: Kimi's ins with "thirty days" -->
<w:ins w:author="Kimi" w:id="500">
  <w:r><w:t>Pay within thirty days.</w:t></w:r>
</w:ins>

<!-- Revised: split Kimi's ins, add Claude's del/ins between -->
<w:ins w:author="Kimi" w:id="500">
  <w:r><w:t xml:space="preserve">Pay within </w:t></w:r>
</w:ins>
<w:del w:id="9001" w:author="Claude" w:date="...">
  <w:r><w:delText>thirty</w:delText></w:r>
</w:del>
<w:ins w:id="9002" w:author="Claude" w:date="...">
  <w:r><w:t>sixty</w:t></w:r>
</w:ins>
<w:ins w:author="Kimi" w:id="9101">  <!-- new unique ID for the suffix -->
  <w:r><w:t xml:space="preserve"> days.</w:t></w:r>
</w:ins>

Assertion pattern for every replacement:

assert old in doc, f"C1: anchor text not found — check XML after unpack"
assert doc.count(old) == 1, f"C1: {doc.count(old)} matches — make anchor more specific"
doc = doc.replace(old, new, 1)

If an assertion fails, your anchor string is either wrong or not unique. Widen the anchor (include more surrounding XML) to make it unique.

Step 6: Add Margin Comments

Use comment.py for each change, starting from max_existing_comment_id + 1:

python .claude/skills/docx/scripts/comment.py unpacked/ 31 "Risk: auto-renewal trap — vendor can raise price unilaterally on renewal. Change: require 90-day written notice and mutual written agreement on new price." --author "Claude"

Then add markers to document.xml around the changed text. Markers are direct children of `<w:p>` — never inside <w:r>:

<w:commentRangeStart w:id="31"/>
<w:del w:id="9001" w:author="Claude" w:date="...">
  <w:r><w:delText>auto-renews at vendor's current rates</w:delText></w:r>
</w:del>
<w:ins w:id="9002" w:author="Claude" w:date="...">
  <w:r><w:t>renewed only upon mutual written agreement on new price</w:t></w:r>
</w:ins>
<w:commentRangeEnd w:id="31"/>
<w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="31"/></w:r>

Step 7: Pack

python .claude/skills/docx/scripts/office/pack.py unpacked/ contract_redlined.docx --original contract.docx

On Windows, if the validator fails with a codec error (GBK), use --validate false:

python .claude/skills/docx/scripts/office/pack.py unpacked/ contract_redlined.docx --original contract.docx --validate false

Then verify the result opens correctly:

import zipfile, xml.etree.ElementTree as ET
with zipfile.ZipFile('contract_redlined.docx') as z:
    ET.fromstring(z.read('word/document.xml'))
    ET.fromstring(z.read('word/comments.xml'))
print("Valid XML — document should open in Word")

Step 8: Generate Summary Document

Create a clean summary .docx using docx-js (see the docx skill). Structure:

CONTRACT REVIEW SUMMARY
[Date] | [Contract title] | [Parties]

EXECUTIVE SUMMARY
[2–3 sentences: overall risk level, key concerns, recommendation]

HIGH-RISK ISSUES  (🔴)
[Issue name]
  Risk: [what could go wrong]
  Location: [clause number]
  Change: [what was modified]

MEDIUM-RISK ISSUES  (🟡)
...

LOW-RISK / NOTES  (🟢)
...

RECOMMENDED NEXT STEPS
...

---

Troubleshooting

| Symptom | Cause | Fix |

|---------|-------|-----|

| Word says "content issues" on open | XML element inside <w:t> | Find <w:del/<w:ins inside <w:t> and restructure at <w:r> level |

| Assertion fails: "anchor not found" | Whitespace/newlines differ post-unpack | Use sed -n 'LINE,LINEp' document.xml to see exact content |

| Assertion fails: "N matches" | Anchor string appears multiple times | Extend old string to include more surrounding context |

| Comment doesn't appear | Markers inside <w:r> instead of as siblings | Move commentRangeStart/End outside any <w:r> block |

| ID collision (del/ins attributed to wrong author) | New IDs overlap existing | Re-scan IDs, pick new starting point |

| Pack fails with "gbk codec" error on Windows | Validator uses wrong encoding | Add --validate false flag |

---

Reference Files

• references/analysis-framework.md — Legal analysis checklist by contract type (SaaS, NDA, employment, services, IP licensing)