Docx

# Docx

Create, edit, and analyze Microsoft Word (.docx) documents at production quality.
This skill encodes hard-won lessons about how Word actually behaves — not how it's
documented — so output looks professional in Word, Google Docs, and Pages.

## Keywords
word, docx, microsoft word, .doc, .docx, word document, letterhead, memo, contract,
report, proposal, table of contents, TOC, headers, footers, page numbers, bullets,
numbered list, tracked changes, comments, redlines, styles, themes, mail merge,
templates, fields, cross-references

## Core Truth

Word documents look simple. They are not. A .docx is a ZIP of XML files with strict
schema requirements. Most "broken" docs come from python-docx writing the right
structure in the wrong order. The rule: use real templates whenever possible. Don't
synthesize formatting from scratch unless you have to.

If the user uploads a docx, edit IN PLACE. Don't recreate it. The original styles,
fonts, and theme are what make it look right.

---

## 1. When To Use

- Generating reports, memos, letters, proposals, contracts
- Editing a user-supplied .docx (fixing typos, applying styles, inserting content)
- Adding tracked changes or comments
- Building a templated document with merge fields
- Producing a deliverable the user will email or print
- Converting markdown/HTML into a properly-styled Word document

## 2. When NOT To Use

- Quick written content that lives in chat → return as markdown
- One-paragraph emails → no doc needed
- Spreadsheet-style data → use xlsx
- Slides → use pptx
- A PDF deliverable → generate docx first then convert

## 3. The Three Modes

| Mode | Trigger | Approach |
|------|---------|----------|
| **Edit existing** | User uploads a .docx | Open file, modify XML directly, preserve everything else |
| **Generate from template** | User has a brand template | Fill placeholders, keep template's styles |
| **Generate from scratch** | No template, brand-new doc | Use python-docx with explicit styles for every paragraph |

Order of preference: Edit > Template > Scratch. Scratch is the last resort.

## 4. Editing Existing Documents

The most common failure mode: regenerating a doc the user already has. If they
uploaded `report.docx` and asked you to fix three typos, fixing those three typos
inside the file is the entire job. Do not rewrite it.

Workflow:
1. Copy the file from /mnt/user-data/uploads to /home/claude
2. Inspect with `unzip -l file.docx` to see what's inside
3. Read `word/document.xml` to find the target content
4. Use python-docx or direct XML edit
5. Save and present

## 5. Tracked Changes

Tracked changes live in `word/document.xml` as `<w:ins>` and `<w:del>` elements.
python-docx does NOT support tracked changes natively. You either:
- Use direct XML manipulation, OR
- Use a library like `python-docx-tracked-changes`, OR
- Decline and explain — sometimes the honest answer

## 6. Tables

Tables are where most docx output goes wrong. Rules:
- Always set table style explicitly (`'Light Grid Accent 1'` or similar)
- Set column widths in EMU (914400 EMU = 1 inch)
- Header row must be marked with `repeat_table_header_rows`
- Don't merge cells unless required — it breaks accessibility

## 7. Common Pitfalls

| Problem | Cause | Fix |
|---------|-------|-----|
| Document opens with "repair needed" | Invalid XML | Validate before saving |
| Fonts wrong in Word | Style not applied; paragraph has direct formatting | Apply named styles, not run-level fonts |
| Page breaks missing | Using `\n\n` instead of section break | Use `WD_BREAK.PAGE` |
| Images not embedded | Linked instead of embedded | Use `add_picture()` not URL reference |
| TOC blank in Word | TOC field needs update | Add instructions to Ctrl+A → F9 |

## 8. Key Questions Before Starting

- Did the user upload a file? If yes — EDIT it, don't recreate it.
- Is there a brand template? If yes — use it.
- What's the final destination — print, email, web, archive?
- Does the user need tracked changes or final-only?
- What's the page size and margins (US Letter vs A4 matters)?

## References
- `references/python-docx-patterns.md` — Working code for every common operation
- `references/xml-manipulation.md` — When python-docx isn't enough
- `templates/` — Letterhead, report, memo, contract starters