fill-protocol

Fill-Protocol スキル

基本原則（必ず守ってください）

1. 既存のテンプレートを開き、最初から作成しないでください。 Document() ではなく Document(template_path) を使用してください。作り直すと、ヘッダーロゴ、カスタム余白、フッターのプレースホルダー、ページ番号が失われます。セルや段落のテキストはその場で置き換えてください。cell.text = "value" のように単一の代入を行うと、run レベルのスタイル（太字、色、eastAsia フォント）が消去されるため、絶対に使用しないでください。
2. 編集の前に、LibreOffice のヘッドレスモードで .doc を .docx に変換してください。 pandoc -f doc はサポートされていません。textutil はテーブル構造を破損させます（結合セルが失われます）。
3. 行・列の座標（table.cell(2, 1) など）ではなく、左側のラベルテキストでセルを照合してください。 テンプレートは変更されるため、座標による照合は気づかないうちに機能しなくなります。
4. 入力したすべての行に cantSplit を適用し、ページをまたいで行が分割されないようにしてください。
5. CJK 言語では、run.font.name だけでなく、eastAsia フォント属性を設定してください。 そうしないと、ハングル・漢字・漢字が代替フォントで表示されます。
6. 入力操作をすべて検証してください。 入力済みフォームを提出する前に、すべての [MISS] 行とすべての WARN: 行（[TABLE-MISS]、[SECTION-MISS]、[RAW-NEWLINE]）を解決してください。

依存関係

Python パッケージの docxtpl python-docx pyyaml は常に必要です。LibreOffice が必要なのは、レガシーな .doc テンプレートを扱う場合のみです（macOS では約 700 MB）。同梱の setup.sh が不足しているものを検出します。

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)

ユーザーに代わってこのスキルを実行する場合：

1. テンプレートがすでに .docx の場合は、LibreOffice を完全にスキップしてください。
2. doc_to_docx.py を呼び出す前に、setup.sh check を実行してください。LibreOffice が見つからない場合、インストールする前にユーザーに確認してください。cask のサイズは約 700 MB です。
3. このセッションでユーザーが無人インストールを明示的に許可していない限り、setup.sh install に --yes を絶対に渡さないでください。渡すと確認なしでインストールされます。
4. ユーザーがインストールを拒否した場合は、.doc を手動で変換するよう依頼してください（Word／LibreOffice／Pages → 別名で保存 → .docx）。その後、変換したファイルを使って再実行してください。

ワークフロー

ステップ 1 — レガシーな .doc を .docx に変換する（必要な場合）

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

ステップ 2 — テンプレートの構造を確認する

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

テーブル、各セル（座標と内容のプレビュー）、最上位の各段落がすべて一覧表示されます。この出力から YAML に使用するラベルを正確に取得してください。

ステップ 3 — コンテンツ YAML を作成する

${CLAUDE_SKILL_DIR}/examples/example_irb_template.yaml をベースにしてください。入力モードは 3 種類あり、すべてのキーは省略可能です。

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 ..."

デフォルト値から読みやすさのオプションを変更する前に、${CLAUDE_SKILL_DIR}/references/best_practices.md（読みやすさの調整項目）を読んでください。

コンテンツのルール：/search-lit で DOI または PMID を確認できた場合のみ、参考文献を記載してください。確認できない場合は [UNVERIFIED - NEEDS MANUAL CHECK] と記してください。未確認の臨床的定義、診断基準、ガイドラインに関する主張には [VERIFY] と記し、ユーザーに確認してください。

ステップ 4 — 入力を実行する

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

CLI は各入力操作について [OK]／[MISS] を出力し、概要の後に WARN: 行を出力します。提出前に、すべての [MISS] と WARN: を調査してください（原則 6）。

table_kv、section_replace、paragraph_replace の各値は、入力したとおりに書き込まれます（012345、12:30、1.10、No はテキストとして保持されます）。値が空の場合、またはリスト／マッピング値の場合、実行は終了コード 2 で停止し、該当するラベルが表示されます。意図的にフィールドを空欄にするには、'' と入力してください。後続に番号付きの見出しがない見出しに対して section_replace を行うと、ドキュメント末尾まですべて置き換わり、置き換えた段落数が [OK] 行に表示されます。署名／日付欄など、最後のセクションの後に続く内容を残すには、section_end を指定して範囲を区切ってください（見出し → 残すブロックの先頭段落に照合する正規表現）。

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

ステップ 5 — 目視確認

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

LibreOffice を利用できない場合（.docx テンプレートでは LibreOffice を使用しません）は、代わりに Word から PDF をエクスポートします。PDF を開き、ページ数が適切であること、表の行がページをまたいで分割されていないこと、フォントが Times New Roman にフォールバックしていないこと、必須フィールドがすべて入力されていることを確認します。

ラベルやセクション見出しが一致しない場合、テンプレートに番号付きセクション見出し（section_end）がない場合、セルに複数行の内容が必要な場合、またはセルが結合されている場合は、${CLAUDE_SKILL_DIR}/references/best_practices.md を参照してください。

既知の制限事項

• HWP / HWPX 入力には直接対応していません — 先に .docx に変換してください。
• 結合セル：垂直方向に結合されたセルに含まれるラベルセルに入力すると、結合領域の内容が上書きされることがあります。まずコピー上でテストしてください。
• 埋め込みフォームフィールド（Word のコンテンツコントロール）：対応していません。通常の段落と表のセルの内容のみが対象です。
• 右から左に記述する文字体系（アラビア語、ヘブライ語）：未テストです。
• 後続の見出しがない最後のセクション：section_end パターンを指定しない場合、ドキュメントの末尾まで置き換えられます。フィラーでは、セクション本文と後続のブロックを判別できません。