fill-protocol

Fill-Protocol Skill

Core Principles (Do Not Violate)

1. Open the existing template — never create from scratch. Use Document(template_path), not Document(): rebuilding loses the header logo, custom margins, footer placeholders and page numbering. Replace cell/paragraph text in place; never a single cell.text = "value" assignment, which erases run-level styles (bold, color, eastAsia font).
2. Convert .doc → .docx via LibreOffice headless before any editing. pandoc -f doc is not supported; textutil corrupts table structure (merged cells dropped).
3. Match cells by left-label text, not row/column coordinates such as table.cell(2, 1). Templates evolve and coordinate matching breaks silently.
4. Apply cantSplit to every filled row so a row never breaks across pages.
5. For CJK languages, set the eastAsia font attribute, not just run.font.name, or Hangul/Kanji/Hanzi render in fallback fonts.
6. Validate every fill operation: resolve every [MISS] line and every WARN: line ([TABLE-MISS], [SECTION-MISS], [RAW-NEWLINE]) before the filled form is submitted.

Dependencies

Python packages docxtpl python-docx pyyaml are always required. LibreOffice is needed only for a legacy .doc template (~700 MB on macOS). The bundled setup.sh detects what is missing:

bash ${CLAUDE_SKILL_DIR}/setup.sh check     # report what's installed (read-only)
bash ${CLAUDE_SKILL_DIR}/setup.sh install   # install missing pieces (asks before each)

When invoking this skill on behalf of a user:

1. Skip LibreOffice entirely if the template is already .docx.
2. Before calling doc_to_docx.py, run setup.sh check. If LibreOffice is missing, ask the user before installing, because the cask is ~700 MB.
3. Never pass --yes to setup.sh install unless the user has explicitly authorized unattended installation in this session, because it installs without prompting.
4. If the user declines, ask them to convert the .doc manually (Word/LibreOffice/Pages → Save As → .docx) and re-run with the converted file.

Workflow

Step 1 — Convert legacy .doc to .docx (if needed)

python3 ${CLAUDE_SKILL_DIR}/scripts/doc_to_docx.py path/to/template.doc path/to/template.docx

Step 2 — Inspect the template structure

python3 ${CLAUDE_SKILL_DIR}/scripts/inspect_template.py path/to/template.docx

It lists every table, every cell (coordinates and content preview) and every top-level paragraph. Take the exact labels for the YAML from this output.

Step 3 — Author a content YAML

Start from ${CLAUDE_SKILL_DIR}/examples/example_irb_template.yaml. Three fill modes; all keys are optional.

protections:
  korean_font: "맑은 고딕"   # CJK font (set to "Noto Sans CJK KR", "SimSun",
                              # "MS Mincho", etc. for other locales)
  cant_split: true            # Apply <w:cantSplit/> to every filled row

  # Readability options (defaults shown)
  blank_between_paragraphs: true            # Enter between \n\n chunks
  blank_around_section_header: true         # Enter above/below filled sections
  blank_around_all_section_headers: false   # opt-in; also touches untouched sections
  normalize_page_breaks: true               # empty page-break paragraphs -> pageBreakBefore

# Mode 1 — table key/value (left-label cell → right value cell)
table_kv:
  "Study Title": "Multi-center prospective validation of ..."
  "Principal Investigator": "Last, First (Department)"
  "연구 목적": "본 연구는 ..."

# Mode 2 — section replacement (find numbered header, replace until next header)
section_replace:
  "1. Background":
    "Hepatocellular carcinoma is the third leading cause of ..."
  "4. 연구 배경 및 이론적 근거":
    "..."

# Mode 3 — single paragraph in-place text replacement
paragraph_replace:
  "Title:":
    "Title: Multi-center prospective validation of ..."

Read ${CLAUDE_SKILL_DIR}/references/best_practices.md (Readability knobs) before changing any readability option from its default.

Content rules: put a reference in only with a /search-lit-confirmed DOI or PMID, otherwise mark it [UNVERIFIED - NEEDS MANUAL CHECK]; mark any unconfirmed clinical definition, diagnostic criterion or guideline claim [VERIFY] and ask the user.

Step 4 — Run the fill

python3 ${CLAUDE_SKILL_DIR}/scripts/fill_form.py \
  --template path/to/template.docx \
  --content  content.yaml \
  --output   path/to/filled.docx

The CLI prints [OK] / [MISS] for every fill operation, a summary, then any WARN: lines. Investigate every [MISS] and WARN: before submitting (Principle 6).

Every value under table_kv, section_replace and paragraph_replace is written exactly as typed (012345, 12:30, 1.10, No stay text). An empty value or a list/mapping value stops the run with exit 2 and names the label; write '' to blank a field on purpose. A section_replace on a header with no later numbered header replaces everything to the end of the document, and its [OK] line says so with the number of paragraphs replaced. If a signature/date block or anything else follows the last section, bound it with section_end (header -> regex matched against the paragraph that starts the kept block):

section_end:
  "18. References": "^Investigator signature"

Step 5 — Visual verification

soffice --headless --convert-to pdf path/to/filled.docx

Without LibreOffice (a .docx template skips it), export the PDF from Word instead. Open the PDF and confirm: page count is sensible, no table row was split across pages, no font fell back to Times New Roman, all required fields are populated.

Read ${CLAUDE_SKILL_DIR}/references/best_practices.md when a label or section header does not match, the template has no numbered section headers (section_end), a cell needs multi-line content, or cells are merged.

Known Limitations

• HWP / HWPX input is not handled directly — convert it to .docx first.
• Merged cells: filling a label cell that participates in a vertical merge may overwrite the merged region's content. Test on a copy first.
• Embedded form fields (Word content controls): not supported; plain paragraph and table cell content only.
• Right-to-left scripts (Arabic, Hebrew): untested.
• Last section with no later header: replaced through the end of the document unless a section_end pattern is given; the filler cannot tell the section body from a trailing block.