docx-toolkit

name: docx-toolkitdescription: >  Audit Microsoft Word (.docx) documents for heading hierarchy, comments,  tracked changes, and style consistency. Use when  reviewing a contract draft, preparing a document for handoff, or enforcing a  style guide.license: MIT + Commons Clausemetadata:   version: 1.0.0  author: borghei  category: documents  domain: document-automation  updated: 2026-05-04  python-tools: docx_auditor.py  tech-stack: docx, OOXML  tags:     - docx    - word    - document-audit    - tracked-changes    - ooxml

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
• Scope & Limitations

---

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, settle the inputs below. When one is missing or vague and would change the result, ask about it; when it wouldn't, use a sensible default and say which one you used.

• 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.

Ask about the two or three inputs that matter most for this request, not the whole list. If the user wants a result straight away, produce it and state your assumptions at the top.

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:
   • 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
3. 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.

---

Scope & Limitations

In Scope:

• Read-only audit of .docx files with scripts/docx_auditor.py, which parses OOXML with zipfile and xml.etree and needs no third-party package
• Word and paragraph counts, heading hierarchy with gap detection, comment count, tracked-changes detection, paragraph styles in use, and hyperlink, image and table counts
• Three workflows: pre-handoff audit, contract review triage, and style-guide enforcement
• A review checklist and templates for allowed styles and pre-send sign-off

Out of Scope:

• Creating or editing .docx files, including accepting tracked changes or deleting comments; the tool only reads
• Reviewing what a contract says (see legal/contract-review/)
• Writing or editing the document's prose (see marketing/copy-editing/)
• Producing formatted documents from markdown (see markdown-html/md-document/)

Important Caveats:

• The auditor reports counts and structure. It does not render the document, so layout, page breaks and visual formatting are not checked.
• It does not compare styles against your allowed list. Style-guide enforcement means reading its style list against the template in assets/ by hand.
• It does not check cross-references or a table of contents for broken targets.
• The triage thresholds, such as more than 20 comments or style sprawl, are rules of thumb. Content errors like a wrong name, jurisdiction or figure need a human read, as the review checklist states.

---

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