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
• Quick Start
• Core Workflows
• Tools
• Reference Guides
• Templates
• Best Practices

Keywords

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

Clarify First

Before running the audit, confirm these inputs. If any is unknown or vague, ASK — do not assume:

• [ ] Audit purpose (pre-handoff cleanup, contract-review triage, or style-guide enforcement) — selects the workflow and the thresholds you apply
• [ ] Recipient (external customer, opposing counsel, internal) — sets the tolerance for leftover comments and tracked changes
• [ ] Allowed style set (for style-guide enforcement) — defines what counts as a non-conforming style

Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.

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:

• Run: python scripts/docx_auditor.py document.docx
• Review the audit output:
• Comment count > 0 → resolve or remove before sending
• Tracked changes detected → accept or reject before sending
• Heading-hierarchy gaps (H1 → H3 with no H2) → restructure
• Style sprawl (more than 8 paragraph styles) → consolidate
• 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:

• Run audit on the returned .docx
• Comment count > 20 or tracked-change paragraphs > 30% → expect a heavy review pass; schedule time
• Comment count < 5 → likely cosmetic; quick turnaround possible
• 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:

• Define allowed styles in your style guide (see assets/style_compliance_template.md)
• Run audit on candidate documents
• Flag any document using styles outside the allowed set
• 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