DOCX Repair

DOCX Repair (Google Docs / Word Online damage)

Cloud editors damage a .docx in independent ways. This skill is the front door for all of them; run only the track(s) you need.

They are decoupled: package repair fixes the part wiring (never touches content); footnote repair fixes the footnote markup; content cleanup strips Google-Docs leftover content controls and normalizes headings. A file can need any, all, or none. If you don't know which, run the package check first (it's a no-op on a clean package), then the footnote pass (it carries the content cleanup).

Heads-up: docx-render's Word path already composes docx_repair.py as a preflight, so a Google export "just renders" without a manual Track A. Run Track A manually when you need the repaired file itself (to hand back, edit, or footnote-fix), not just a PDF.

Reference index — read the file for the track you are running

All procedural detail lives in references/. Read only what the job needs.

• references/package-repair.md — Track A. The two concrete Google Docs export defects (case-mismatched customXML/customXml OPC part references; leftover <w:evenAndOddHeaders/>), and the CLI + Python API for scripts/docx_repair.py at plugin root. Read when Word calls the file corrupt, refuses to open it, or shows a phantom blank page — or before handing back a repaired file rather than a PDF.

• references/footnote-procedure.md — Track B, the canonical procedure. The exact four-step order for a Google Docs round-trip (accept changes → fix_footnotes.py → create_crossrefs.py --baseline → render with Word), what to verify in the render, the incident-grounded procedure facts (why step 3 must follow step 2, why --baseline is not optional, why LibreOffice lies), the list of symptoms footnote repair applies to, and the quick-start "which script do I want?" routing. Read when running any footnote repair — start here.

• references/footnote-scripts.md — Track B, script detail. Per-script behaviour and every flag for fix_footnotes.py, create_crossrefs.py (including how --baseline remaps stale numbers) and refresh_noteref_caches.py (why the naive approaches fail, its requirements and intentional scope), plus the footnote numbering-offset fix (numRestart). Read when you need a specific flag, or the exact semantics of one of the three scripts.

• references/footnotes-reference.md — Track B, OOXML technical reference. (1) Run-level editing gotchas (NBSP, cross-run matching, xml:space); (2) cloud editor damage patterns — what gets destroyed and why; (3) direct ZIP surgery patterns that bypass Document libraries; (4) the numbering-restart details and the critical rule that numRestart goes in settings.xml ONLY. Read when hand-editing footnote XML or debugging behaviour the scripts do not cover.

• references/content-cleanup.md — Track C. The four content passes fix_footnotes.py carries: stripping goog_rdk content controls (the "boxes", default on), heading normalization (--normalize-headings), the OOXML hygiene / de-cruft rules (default on, with the exact strip/keep lists), body-indent normalization (--normalize-body-indent), and applying the template's body styles (--restyle-body), plus the content-cleanup incident facts. Read when boxes, inconsistent headings, stray indents or XML bloat are the complaint, or before passing any of those flags.

• references/presentation-hygiene.md — Track D. docx_links.py (tracking-param stripping, SSRN canonicalization, footnote hyperlink unwrapping — and why display text and relationship Target must both be rewritten) and docx_spacers.py (manual spacer removal, why a text-empty paragraph may not be empty, the title-page collapse hazard), plus why both edit bytes rather than the ElementTree tree. Read when the PDF shows blue/underlined footnotes, a link that navigates elsewhere, or uneven heading gaps.

Related (document skill group)

This skill owns the REPAIR stage — package wiring (Track A), footnote markup (Track B), and document-content cleanup (Track C) — for a .docx damaged by a cloud editor. Adjacent stages:

• Build a styled .docx from markdown → law-review-docx (its build_docx.py chains this skill's footnote repair + NOTEREF conversion after the pandoc build).
• Render to PDF/PNG → docx-render / scripts/doc_render.py (Word path composes Track A's docx_repair.py as a preflight automatically).
• Check cross-references before believing them. check_crossrefs.py is the only pass that READS the target note: it verifies the short form names a source the target actually contains, on top of existence and direction. create_crossrefs.py --dry-run proves only that note N exists and will report "25 targets, 25 valid" over a document whose cites point at the wrong documents — it is a conversion preflight, not an audit. Run check_crossrefs.py on any draft returned by a coauthor, and after every renumber. It name-matches loosely (any capitalised word in the short form appearing in the target), so it catches a cite aimed at the wrong source, never a wrong pincite.
• Footnote repair lives only here. fix_footnotes.py is the single canonical Google-Docs / Word-Online footnote fixer; there is no second copy. (Bluebook's create_crossrefs.py + audit_crossref_targets.py remain a deliberate, actively-used cross-reference fork with their own retargeting strategy — a different concern, not a footnote-fix duplicate.)

See the full document skill group.