DOCX Repair (Google Docs / Word Online damage)

What this skill carries — grep references/ for any subject the names below miss: !d=${CLAUDE_SKILL_DIR}; command -v skill-toc >/dev/null 2>&1 && exec skill-toc "$d"; s=$HOME/.claude/skills/plugin-utils/bin/skill-toc; [ -x "$s" ] && exec "$s" "$d"; echo "(skill-toc unavailable: references and scripts are NOT listed here — install the plugin-utils plugin, or start a new session so its bin/ reaches PATH)"

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.

Damage class	Symptom	Fix
A. Package / OOXML wiring	Word pops "recover unreadable content?" or refuses to open; LibreOffice won't load; phantom blank page	${CLAUDE_PLUGIN_ROOT}/scripts/docx_repair.py (plugin root) — references/package-repair.md
B. Footnote & cross-reference markup	Bios show 1,2,3 not *,†,‡; numbering starts wrong; "supra note N" points to the wrong footnote; missing separator line	the footnote scripts — references/footnote-procedure.md
B1. Cross-references aimed at the wrong source	Lin, supra note 130 where note 130 is a different work; Rebuttal Report, supra note 22 where 22 defines the deposition; a short form surviving a renumber that moved its target	check_crossrefs.py <file.docx> — read-only, exit 1 on any problem
C. Document content (boxes + headings + cruft)	Visible boxes around freshly-edited text; heading-looking lines not styled as headings; same-style headings rendering differently; blank heading lines; bloated XML full of all-zero rsids, no-op shading, explicit b=0/i=0/u=none, redundant black color & default fonts	fix_footnotes.py's document.xml passes — references/content-cleanup.md
D. Presentation hygiene	A footnote renders blue/underlined in the PDF but looks normal in Word; a URL prints one address and navigates to another; heading gaps uneven page to page; tracking params (?utm_source=…) behind a clean-looking link	docx_links.py, docx_spacers.py — references/presentation-hygiene.md

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 ${CLAUDE_PLUGIN_ROOT}/scripts/docx_repair.py. 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 / ${CLAUDE_PLUGIN_ROOT}/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.