docx-toolkit

Docx Toolkit

Audit .docx files using the standard library only — no python-docx required. Reads OOXML directly with zipfile + xml.etree.

Table of Contents

• [Keywords](#keywords)
• [Quick Start](#quick-start)
• [Core Workflows](#core-workflows)
• [Tools](#tools)
• [Reference Guides](#reference-guides)
• [Templates](#templates)
• [Best Practices](#best-practices)

Keywords

docx, Word, Microsoft Word, document, document review, comments, tracked changes, redline, headings, style guide, word count, document audit

Quick Start

python scripts/docx_auditor.py contract.docx

Outputs: word count, paragraph count, heading hierarchy, comment count, tracked-changes status, hyperlink count, list of unique paragraph styles used.

Core Workflows

Workflow 1: Pre-Handoff Document Audit

Goal: Catch the issues that embarrass a sender — leftover comments, unresolved track changes, broken heading hierarchy — before the document leaves.

Steps:

1. Run: python scripts/docx_auditor.py document.docx
2. Review the audit output:
3. Comment count > 0 → resolve or remove before sending
4. Tracked changes detected → accept or reject before sending
5. Heading-hierarchy gaps (H1 → H3 with no H2) → restructure
6. Style sprawl (more than 8 paragraph styles) → consolidate
7. Re-run until clean

Time Estimate: 5-15 minutes per document.

Workflow 2: Contract Review Triage

Goal: Quantify how much rework a returned contract needs before reading it line-by-line.

Steps:

1. Run audit on the returned .docx
2. Comment count > 20 or tracked-change paragraphs > 30% → expect a heavy review pass; schedule time
3. Comment count < 5 → likely cosmetic; quick turnaround possible
4. Use references/docx_review_checklist.md for the actual content review

Time Estimate: 1 minute per document for triage.

Workflow 3: Style-Guide Enforcement

Goal: Detect documents drifting from your style guide before they ship to a customer.

Steps:

1. Define allowed styles in your style guide (see assets/style_compliance_template.md)
2. Run audit on candidate documents
3. Flag any document using styles outside the allowed set
4. Map non-conforming paragraphs back to standard styles

Time Estimate: 2-5 minutes per document.

Tools

docx_auditor.py

Reads a .docx file as a ZIP archive and parses OOXML directly. No external dependencies.

# Human-readable
python scripts/docx_auditor.py document.docx

# JSON
python scripts/docx_auditor.py document.docx --json

Reports:

• Word and paragraph counts
• Heading hierarchy (with gap detection)
• Number of comments
• Whether tracked changes are present
• Unique paragraph styles used
• Hyperlink count
• Image count
• Table count

Limits: This tool reads existing docx files. For generating docx, use the templates in assets/ and edit in Word, or install python-docx separately.

Reference Guides

• references/docx_review_checklist.md — Pre-handoff checklist; common rework triggers; mistakes that survive automated audits

Templates

• assets/style_compliance_template.md — Format for declaring allowed paragraph styles
• assets/handoff_checklist_template.md — Pre-send checklist with sign-off boxes

Best Practices

• Audit before every external send. A 30-second audit catches 80% of avoidable embarrassment.
• Resolve comments before "Final v3.docx". Files named "final" with active comments are how lawyers get tickled.
• Lock heading hierarchy. H1 → H3 with no H2 breaks navigation, accessibility, and table-of-contents generation.
• Prefer styles over inline formatting. A style change in one place beats hundreds of inline overrides.

Integration Points

• Pairs with legal/ skills for contract redlines
• Pairs with marketing/copywriting/ for content review
• Used by c-level-advisor/board-deck-builder for board-pack documents