/fill-protocol

name: fill-protocol
description: Use when an institutional Word form (.doc/.docx IRB protocol, ethics application, grant template) must be filled without breaking its styles, tables, fonts or page layout. Renders content drafted by /write-protocol into the template; CJK-aware.
metadata:
  triggers: "fill protocol, fill template, fill IRB form, IRB template, ethics template, grant template, 양식 채우기, 연구계획서 작성, 신청서 작성, 정부 양식, 병원 양식, 워드 템플릿"

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.