fill-icmje-coi

Fill-ICMJE-COI Skill

The official ICMJE coi_disclosure.docx keeps every field inside Word Content Controls (SDTs), which python-docx cell.text silently ignores. The script therefore does literal-string replacement in word/document.xml, which only works when the target strings already exist — hence the shipped pre-filled synthetic seed.

Core Principles (Do Not Violate)

1. Never author SDT XML from scratch. Only replace existing strings in an already-populated seed, because programmatic Content Controls are fragile and Word-version-dependent. If an error seems to require altering the seed structure, stop and escalate to the user.
2. Never use or commit a seed that contains a real author's data. The shipped templates/icmje_coi_seed_synthetic.docx is PII-scrubbed (synthetic name, title, date; metadata ICMJE / Anonymous); real-person seeds leak PII through both document.xml and docProps. Keep custom seeds with real names in private per-project directories, and before promoting any seed check unzip -p seed.docx docProps/core.xml for real names.
3. Never modify the 13 disclosure items or the certification checkbox. The script replaces only Date, Name and Title; the ☒ None entries come from the seed unchanged. Never say the script "handled the disclosures": it cloned the seed, and no author-specific disclosure reasoning happened. An author with a real disclosure edits their own form in Word.
4. The seed must be pre-filled (all-None ☒ + text). The script does not work on a blank ICMJE template.

Skip this skill when the target journal uses its own declaration form (Elsevier Declaration of Interest, a BMJ ICMJE derivative, etc.) rather than the canonical ICMJE form — check the author guidelines first.

Execution

Phase 1 — Intake

Ask the user (or extract from the conversation):

1. Manuscript title (exact, as on the title page)
2. Submission date (e.g., "April 20, 2026")
3. Author list — ordered, one name per slot: [(1, "Author One"), (2, "Author Two"), ...], taken verbatim from the manuscript title page or the user's list
4. Output directory — typically submission/{journal}/icmje_forms/

Gate 1 — user approval. Present the intake back before generating anything. Name which authors will get all-None forms and remind the user that anyone with a real disclosure must fill their own form in Word instead.

Phase 2 — Generate

python3 ${CLAUDE_SKILL_DIR}/scripts/fill_icmje_coi.py \
  --seed ${CLAUDE_SKILL_DIR}/templates/icmje_coi_seed_synthetic.docx \
  --seed-name "Placeholder Author" \
  --seed-title

It writes one ICMJE_COI_{NN}_{Name}.docx per author and exits nonzero if any seed string is not found. It exits 2, before writing anything, if any --seed-* or --new-* value or author name is empty: an empty seed string would match nothing and leave the seed's value in every form.

Phase 3 — Verify

For each generated docx confirm: ☒ count = 14 (13 disclosure items + final certification); "None" disclosures = 13; the correct name after "Your Name:" and title after "Manuscript Title:"; no seed strings left. SEED must be the exact --seed-name, --seed-title and --seed-date values used in Phase 2 (the shipped placeholders below, or a custom seed's own strings); TITLE must be the --new-title value.

This snippet does not locate the name inside the "Your Name:" field; confirm the name by opening each form.

Gate 2 — user review. Present the verification results before handing off the files.

Phase 4 — Circulation Guidance

Give the user this copy to send with each personalized form, written in the co-authors' language:

Please review the attached ICMJE COI form.

• If the contents are correct, sign and reply with a PDF.
• If a change is needed, edit/check the relevant item, sign, and reply.
• If there are no changes at all, reply "no changes" and return the signed PDF separately.

All authors can be emailed in one draft batch (e.g., gws gmail draft). Gate 3 — the user approves the batch before anything is sent.

Custom Seeds and Seed Provenance

Read ${CLAUDE_SKILL_DIR}/references/seeds.md when the user wants a custom seed (different default wording, a common grant pre-filled in items 2/3) or asks how the shipped seed was made.