Agent Skills: Law Review DOCX Export

Law Review DOCX Export

Convert markdown drafts into a properly formatted Word document using the law review template via pandoc.

This is the ONLY correct way to build a law-review .docx — never hand-roll pandoc/soffice; the template, footnote handling, TOC, and table styling all live in build_docx.py. Agents without the Skill tool (most workflow subagents) can't invoke this skill — run the script below directly:

Usage

uv run python3 ${CLAUDE_SKILL_DIR}/scripts/build_docx.py PROJECT_DIR [--output PATH] [--fix-footnotes]

The script:

1. Detects title/author from .planning/ACTIVE_WORKFLOW.md or PRECIS.md
2. Combines all drafts/*Draft*.md files in section order (Introduction → Parts → Conclusion → Appendix)
3. Strips YAML frontmatter and prefixes footnote labels to avoid cross-section collisions
4. Resolves <!-- include: PATH --> sentinels by inlining file contents (paths must be absolute or ~-expanded)
5. Runs pandoc with --reference-doc pointing to the law review template
6. Optionally runs the docx-repair repair script (--fix-footnotes)

Compile-Time Includes

To embed externally generated tables or fragments at build time, place a sentinel in the draft:

<!-- include: ~/projects/mirror/data/tables/paper/table2_body.md -->

The preprocessor expands ~, reads the file, and splices its contents inline before pandoc runs. Missing or non-absolute paths emit a visible <!-- MISSING: ... --> placeholder instead of failing silently. For images, use plain pandoc markdown (![caption](~/path/to/figure.png)) — no sentinel needed.

Detecting the Project Directory

If the user doesn't specify a path, detect it from context:

1. Check if current working directory has drafts/ and .planning/
2. Check if .planning/ACTIVE_WORKFLOW.md exists and read project_dir from it
3. Follow symlinks (e.g., paper → actual project directory)

Template

The reference template lives at:

${CLAUDE_PLUGIN_ROOT}/references/templates/law_review_template.docx

This template defines all styles that pandoc applies:

| Style | Use | Formatting | |-------|-----|------------| | Title | Article title | Bold, small caps, centered | | Heading 1 | Part titles (I., II., III.) | Bold, left-aligned | | Heading 2 | Sections (A., B., C.) | Bold, left-aligned | | Heading 3 | Subsections (1., 2., 3.) | Italic, left-aligned | | Body Text | All body paragraphs | First-line indent | | First Paragraph | After headings | No indent | | Footnote Text | Footnotes | 10pt, single-spaced |

Figures: vector, via svgBlip

Reference the PNG in markdown — ![caption](~/figures/fig1.png) — and keep a same-stem .svg beside it. After pandoc, build_docx.py finds each embedded raster, matches it to its SVG by content hash (pandoc rewrites media to rIdN.png, so the filename is gone by then), and attaches the vector:

<a:blip r:embed="rIdPng">
  <a:extLst>
    <a:ext uri="{96DAC541-7B7A-43D3-8B79-37D633B846F1}">
      <asvg:svgBlip xmlns:asvg="http://schemas.microsoft.com/office/drawing/2016/SVG/main"
                    r:embed="rIdSvg"/>
    </a:ext>
  </a:extLst>
</a:blip>

Word 2016+ draws the SVG with its own renderer; everything older falls back to the PNG. No sibling .svg, no change — raster-only projects are unaffected.

Never reference a bare .svg from markdown. Pandoc embeds it as an image part with no svgBlip, unzip -l shows the media happily, and Word renders nothing — blank space under the caption, no error at any stage.

Never convert SVG→EMF with LibreOffice as a substitute. EMF is a real vector format and Word draws it, so the route looks correct. It is not: LibreOffice's SVG importer silently corrupts complex figures. A five-facet histogram came back missing an entire facet row, every row label, both axis labels, the tick numbers and the zero line — still a plausible-looking chart, so nothing downstream flagged it. Simple one-panel figures convert fine, which is what makes it dangerous: verifying one figure proves nothing about the rest.

Verification — count images in the RENDERED PDF, never in the DOCX:

pdfimages -list manuscript.pdf | tail -n +3 | wc -l   # 0 == every figure is vector

A media part exists for formats Word cannot draw, so a word/media/ count is not evidence the figure reached the page. Check the most structurally complex figure against its source, not the first one.

After Export

Report the output path, section count, footnote count, and approximate word count. If the user needs further formatting (NOTEREF cross-references, footnote repair from cloud editing), suggest --fix-footnotes or the docx-repair skill.

Typographic Widows

build_docx.py sets Word's paragraph-level widowControl, which prevents a paragraph's last line from landing alone on the next page — it does nothing about a last line holding one or two stray words. Two companion scripts handle that, after compiling to PDF:

# Report widows (paragraph last lines of 1-2 short words, main column only)
uv run python3 ${CLAUDE_SKILL_DIR}/scripts/check_widows.py OUTPUT.pdf [--max-words N] [--verbose]

# Same detection, then bind the last two words in the offending drafts/*.md
# paragraph with a pandoc non-breaking space. Recompile afterwards.
uv run python3 ${CLAUDE_SKILL_DIR}/scripts/fix_widows.py OUTPUT.pdf PROJECT_DIR [--dry-run]

Run --dry-run first: fix_widows.py edits source markdown, and the fix is only meaningful against the PDF it was measured on. Iterate compile → check → fix → recompile.

Rendering to PDF (Word fidelity, incl. from background jobs)

build_docx.convert_to_pdf() delegates to doc_render.convert(renderer="word"), which uses Microsoft Word's engine for line-exact layout (best for widow detection) and faithful tables.

Note on table fidelity: for tables this skill builds, the wrap_cell pass (see style_tables) already pre-breaks cells with explicit <w:br/> so soffice and x2t render the grid too (commit ec349c5), and x2t kerning is corrected by doc_render's GPOS/kern injection + EB-Garamond substitution. So all three engines are grid-faithful for build-generated tables; Word is preferred for polish, not required for table integrity. Word matters most for hand-authored docx whose tables never pass through wrap_cell — LibreOffice collapses such a table to a single stacked column whenever a cell must auto-wrap (Word/x2t keep the grid).

Word is GUI-driven, so a detached Claude background job can't drive it directly (AppleEvents fail with -600 — it's in a non-console GUI session without Word's TCC grant). doc_render handles this transparently by dispatching the render into a cmux pane (which lives in the console GUI session and is TCC-granted). One-time host prerequisites:

• cmux socket control enabled: automation.socketControlMode ≠ "cmuxOnly" in ~/.config/cmux/cmux.json, then cmux reload-config.
• Microsoft Word granted to cmux under System Settings → Privacy & Security → Automation, and Word in Full Disk Access.

Set $DOC_RENDER_NO_CMUX=1 to disable the cmux path (then background jobs fall back to x2t/LibreOffice). See docs/investigations/2026-06-22_word-render-cmux-dispatch.md.

Known Gotcha: Pandoc-Citeproc Paren-Wrap Inside Footnotes

Symptom. In the compiled DOCX, some footnotes read with a doubled space and wrapping parens around a citation:

see  (Griffin, supra note 12; Macey, supra note 12). For proponents...

(note the two spaces before ().

Root cause. Pandoc-citeproc wraps any bracketed parenthetical citation [@key] or [signal @key] in parens with a leading space when it appears mid-paragraph inside a footnote body. At the paragraph start the wrap is suppressed; mid-paragraph it is not. This is native pandoc behavior for note-style CSLs and cannot be fixed at the CSL level.

Why the natural-looking fix doesn't work. Rewriting source to bare textual form (@key without brackets) renders cleanly only if every citation has a locator. For bib entries without locators (books, misc, many articles), pandoc-citeproc with a note-style CSL emits just a stray number (1.) because the full cite is supposed to go into a footnote and there is no footnote to host it (we're already inside one).

Fix. The docx-repair skill's fix_footnotes.py detects and strips these wraps post-compile. The detector keys on the distinctive XML signature:

<w:r><w:t xml:space="preserve"> </w:t></w:r>     <!-- natural space -->
<w:r><w:t xml:space="preserve"> </w:t></w:r>     <!-- EXTRA space -->
<w:r>…<w:t>(Author,</w:t></w:r>                  <!-- open paren run -->
… citation content …
<w:r>…<w:t>)</w:t></w:r>                         <!-- close paren (standalone or attached) -->

Author-written explanatory parentheticals ((describing X), (documenting Y)) appear as a single <w:t> (…)</w:t> run and lack the double-whitespace signature, so they are preserved. build_docx.py runs fix_footnotes.py automatically when --fix-footnotes is set (the default).

Title-page spacing

Front matter is usually unstyled Normal, which defines no spacing, so the title page's rhythm rides on manual empty paragraphs. Measured norms from six published typesets, which one to copy (Griffin — the manuscript-laid-out one, uniform 2.0×, not the ~4× journal-page average), and the page-one fit trap: references/title-page-spacing.md.

Red Flags

| Action | Why Wrong | Do Instead | |--------|-----------|------------| | Running pandoc -o output.docx without --reference-doc | Produces default Calibri formatting that violates journal requirements | Always use the template | | Manually constructing the DOCX with python-docx or docx-js | Reinvents what the template + pandoc already handle | Run the script | | Combining markdown without prefixing footnote labels | Causes footnote collisions when multiple sections use [^1] | The script handles this automatically | | Referencing a bare .svg from markdown | Pandoc writes no svgBlip, so Word renders nothing — blank space under the caption, no error | Reference the PNG; keep the .svg beside it and let the build attach it | | Converting SVG→EMF with LibreOffice to get vector into Word | Its SVG importer silently drops facet rows, row labels, axis labels and reference lines from complex figures | Use the svgBlip path the build already implements | | Confirming figures embedded by counting word/media/ entries | A media part exists for formats Word cannot draw | pdfimages -list the rendered PDF | | Declaring the figure pipeline verified after checking one figure | Converters that mangle complex figures handle simple ones fine | Verify the most structurally complex figure |