docx-toolkit · diff
v1.0.0 to v1.0.0
10 added, 0 removed. Audit A to A.
---
name: docx-toolkit
description: >
Audit Microsoft Word (.docx) documents for heading hierarchy, comments,
tracked changes, broken cross-references, and style consistency. Use when
reviewing a contract draft, preparing a document for handoff, or enforcing a
style guide.
license: MIT + Commons Clause
metadata:
version: 1.0.0
author: borghei
category: documents
domain: document-automation
updated: 2026-05-04
python-tools: docx_auditor.py
tech-stack: docx, 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](#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
---
+ ## 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
```bash
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.
```bash
# 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