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 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) ```bash python3 ${CLAUDE_SKILL_DIR}/scripts/doc_to_docx.py path/to/template.doc path/to/template.docx ``` ### Step 2 — Inspect the template structure ```bash 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. ```yaml 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 ```bash 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): ```yaml section_end: "18. References": "^Investigator signature" ``` ### Step 5 — Visual verification ```bash 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.