fill-icmje-coi

Files (6)

• SKILL.md
• seeds.md · references/
• fill_icmje_coi.py · scripts/
• skill.yml
• icmje_coi_seed_synthetic.docx · templates/
• test_fill_icmje_coi.sh · tests/

SKILL.md (first lines)

# 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

```bash
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 "Placeholder Manuscript Title" \
  --seed-date "January 1, 2000" \
  --new-title "{exact manuscript title}" \
  --new-date "{submission date}" \
  --out-dir {out_dir} \
  --authors '[[1,"Author One"],[2,"Author Two"],...]'
```

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.

```bash
python3 - {out_dir}/*.docx <<'PY'
import sys, zipfile
SEED = ("Placeholder Author", "Placeholder Manuscript Title", "January 1, 2000")  # = --seed-* values
TITLE = "{exact manuscript title}"                                                 # = --new-title
assert all(s.strip() for s in SEED) and TITLE.strip(), "empty SEED/TITLE value"
for f in sys.argv[1:]:
    xml = zipfile.ZipFile(f).read("word/document.xml").decode("utf-8")
    assert xml.count("☒") == 14, f"{f}: bad ☒ count"
    assert xml.count(">None<") + xml.count(">None ") == 13, f"{f}: bad None count"
    for ph in SEED:
        assert ph not in xml, f"{f}: seed leak {ph!r}"
    t = TITLE.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
    assert t in xml, f"{f}: title missing"
    print("✓", f)
PY
```

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.

From Aperivue/medsci-skills, MIT.

More from Aperivue/medsci-skills