--- name: document_formatting_audit description: Find formatting drift in a Word docx by comparing the document against itself: resolve each paragraph's effective formatting through the docDefaults and based-on style chain, with direct formatting last, group paragraphs by style, and report grouped defects with the fix for each kind, plus an explicit list of what was not inspected. Ships a tested standard library resolver and a planted defect test document with a scored answer key. Use when a docx looks inconsistent, pasted text brought foreign fonts or sizes, headings or body text drift between sections, or a document needs a formatting cleanup before it ships. --- # Document Formatting Audit ## Purpose Find where a Word document disagrees with itself. A docx stores formatting in layers: document defaults, a chain of styles linked by Based On, and direct formatting pasted or typed on top. The visible fault, one paragraph in the wrong size, is usually a direct value beating the style, and it will not move when the style is fixed. This skill resolves every paragraph's effective formatting through those layers, groups paragraphs by the style they claim to follow, and reports the ones that break their own group's pattern. No external style guide is needed, and none is invented. The document is its own standard. ## Workflow 1. **Copy the file before touching anything.** Audit the copy. The audit tool only reads, but the fixes that follow it do not, and a formatting cleanup is hard to undo by eye. 2. **Run the resolver first.** `python3 bin/audit_docx.py FILE.docx --json report.json` from this skill's folder. It reads `word/styles.xml` and `word/document.xml` with the Python standard library only, resolves effective paragraph properties and the effective properties of each paragraph's longest run, and prints defects grouped by kind plus the uninspected list. Exit 0 means no defects in what was inspected, exit 1 means defects found, exit 2 means the file could not be read. Read `references/resolution-order.md` before arguing with its output: it sets out the layer order, the units (spacing in twentieths of a point, font size in half points), and the toggle property trap. 3. **Check the style level faults first.** Broken Based On links, based-on cycles, and undefined styles corrupt every resolution below them. If the report carries any of those, they are the headline findings and the likely cause of a share of the paragraph findings. Note them, and plan to rerun after they are fixed before doing paragraph cleanup. 4. **Read outliers against their group.** For each `group_outlier`, look at the group value, the paragraph's value, and its text preview. A group under 3 paragraphs is not scored, and a property with no strict majority has no consensus to drift from, so neither appears. If a style group splits evenly between two values, write that split up as a finding in your own words: two different uses are sharing one style name. 5. **Read direct overrides with the text sample in view.** A `direct_run_override` on a whole pasted paragraph is drift. A `direct_run_override` on one bold word mid sentence is usually deliberate emphasis. The defect list shows a text sample for every run finding. Sort findings into confirmed drift, deliberate exception, and needs a human call. Never present raw tool output as confirmed faults without this pass. 6. **Match each confirmed fault to its fix.** Use `references/defect-kinds.md`. The short version: style value intended means clear the direct formatting (Ctrl+Q for paragraph formatting, Ctrl+Space for character formatting in Word), everyone should change means edit the style, one paragraph is special means keep it and record it as a deliberate exception. Direct overrides and outliers on the same paragraph and property are one fault seen two ways. Count them once. 7. **State what was not inspected, by name.** Copy the tool's uninspected list into the report and add anything your own run skipped, such as a second file, tracked change formatting judged as stored rather than as accepted, or table style banding. A report that says a file is clean without this list has overclaimed. 8. **Verify the tool when the stakes justify it.** `python3 tests/make_test_docx.py` rebuilds the planted test document and its answer key, then run the audit on `tests/test_document.docx` and score it with `python3 tests/score_audit.py report.json`. The expected result is 9 of 9 planted defects, no false positives, and no defects on clean paragraphs. Run this before trusting the tool on a new Python version or after editing it. ## Output Contract - Header: file name, paragraph count, and the style groups with their sizes. - Defects grouped by kind, worst first: style level faults, then undefined styles, then group outliers and direct overrides merged per paragraph so one fault is counted once. - Each defect: paragraph number counting from 0 as the tool reports it, a short text preview so a person can find the paragraph, the property, the group or style value, the actual value, and the fix that fits the kind. - A deliberate exceptions list: direct formatting the audit found and the report judges intentional, with the reason in one line each. These stay in the document and should not be reflagged as surprises next time. - An uninspected list, copied from the tool and extended with anything else not checked. The verdict line must match it: "no drift found in body paragraphs and styles" is an allowed verdict, "the document is clean" is not. - Counts that add up: total defects by kind from the tool, then confirmed drift, deliberate exceptions, and needs a call, summing to the same total after merging double views of one fault. ## Operating Rules - Compare like with like only. A Heading 1 paragraph and a body paragraph are supposed to differ. Every comparison in this skill happens inside one style group. - Direct formatting is a finding, not a verdict. It overrides styles by design, and authors use it on purpose. The report separates what the tool found from what a reader judged. - Never recommend Clear All Formatting as a bulk fix. It strips deliberate character formatting along with drift. Fix by kind and by group, smallest change first. - Fix style level faults before paragraph level ones, and rerun the audit between the two. Paragraph findings counted against a broken chain are not real counts. - Report values in points, as the tool does. The file stores twentieths of a point and half points; do not hand a user raw stored values without conversion. - Treat toggle properties with care. Bold and italic can toggle in style versus direct combinations. If one flagged paragraph turns on bold or italic alone, check it in Word before prescribing a fix. - Do not claim anything about rendered layout. Pagination, line breaks, and font substitution depend on the machine that opens the file. This audit covers stored formatting only, and says so. - No em dashes in the report. Plain sentences, real numbers, and the text previews as evidence.