IRB-in-Hurry: Automated IRB Form Generator for KFSYSCC

Turn one YAML file into a complete, submission-ready IRB packet — DOCX + PDF, in seconds.

Quick Start · Form Coverage · Usage · FAQ · 繁體中文

⏱️ It's 11:47 PM. The IRB deadline is tomorrow.

You have a brilliant retrospective study. You also have five Word forms, each wanting the same IRB number, the same bilingual title, the same PI phone extension, and a very particular opinion about whether a checkbox is ■ or □. You've typed your own name in 標楷體 eleven times tonight. The twelfth time, you misspelled it.

IRB-in-Hurry is the colleague who stays late so you don't have to. Describe your study once in config.yml, run make all, and it:

1. 🧭 Figures out which forms you need, based on study type and submission phase
2. 📝 Fills every one of them in: headers, titles, checkboxes, dates, and the rest
3. 🖨️ Exports PDFs with embedded fonts that look the same on Windows and Mac
4. 🔍 Checks the layout against the official blank forms before a reviewer can catch a problem
5. ✅ Gives you a ■/□ checklist of what's left (signatures, attachments, the email to the IRB office)

It's an open-source IRB form generator and research ethics paperwork automation tool for the Koo Foundation Sun Yat-Sen Cancer Center (KFSYSCC, 和信治癌中心醫院) Institutional Review Board. It covers all 11 submission categories and 43 official forms: new case, amendment, continuing review, closure, SAE reporting, and more.

It won't do your ethics thinking for you, and that's the point. It does the typing.

Why This Exists

The Institutional Review Board (IRB) is one of the most important inventions in the history of medical research. Born from the ashes of the Nuremberg Trials (1947) and codified through the Declaration of Helsinki (1964) and the Belmont Report (1979), the IRB exists to ensure that no human being is subjected to research without informed consent, proper risk assessment, and ethical oversight. These are non-negotiable principles. The horrors of Tuskegee, Unit 731, and countless other episodes of unchecked medical experimentation remind us why.

But somewhere along the way, the bureaucracy ate the mission.

What was meant to protect human subjects has calcified into a paperwork marathon. At KFSYSCC alone, researchers must navigate 11 submission categories and 43+ forms — each with its own version number, formatting requirements, and checkbox conventions. A single retrospective chart review (minimal risk, no patient contact, de-identified data) requires 5 forms. A clinical trial? Double that. An amendment to fix a typo in your protocol? Another 4 forms.

The researcher's time is finite. Every hour spent copying IRB numbers into the header of form SF037 is an hour not spent analyzing data, writing manuscripts, or — most importantly — caring for patients. The forms themselves are not the problem. The problem is that filling them out is mindless, repetitive, error-prone labor that a machine should do.

This project does not bypass the IRB. It does not skip ethical review. It does not auto-approve anything. It simply fills in the forms that the IRB requires, using the data you provide, so you can focus on the parts that actually require human judgment: study design, risk assessment, and the protection of your participants.

"The ethics of research is in the design, not the paperwork."

IRB-in-Hurry: because your time is better spent on science.

Features

• 11 IRB categories supported: new case, amendment, continuing review, closure, SAE, IB update, import, suspension, appeal, re-review, and other
• 43 form generators with automatic selection based on study type and submission phase
• Smart routing: retrospective study automatically selects expedited review + consent waiver forms
• DOCX generation using python-docx with proper formatting (standard KaiTi font, ■/□ checkboxes)
• PDF + PNG preview pipeline for visual validation
• Plain-text checklist (■/□) tracking both generated forms and manual steps
• Color-coded dashboard for submission status overview
• Claude Code skill for AI-assisted form preparation

Form Coverage

All forms from the KFSYSCC IRB website are implemented:

Quick Start

# 1. Clone and setup
git clone https://github.com/htlin222/irb-in-hurry.git
cd irb-in-hurry
make setup

# 2. Edit config.yml with your study details
#    (or copy the example fixture)
cp tests/fixtures/sample_retrospective.yml config.yml

# 3. Generate everything
make all

Usage

Makefile Commands

Workflow

config.yml → generate_all.py → output/*.docx → convert.py → output/*.pdf
                                                           → output/preview/*.png
                                  checklist.md ← checklist.py
output/*.docx + templates/official/ (官方空白表單) → validate_layout.py
                                                 → output/layout_report.md
                                                 → output/preview/compare/*.png

1. Edit config.yml — Fill in study metadata (IRB number, titles, PI info, dates, study type)
2. make all — Generates DOCX forms, converts to PDF, shows dashboard
3. Layout gate — make validate must report 0 errors; open output/layout_report.md
   and output/preview/compare/*.png (official blank left, generated right)
4. Submit the PDF — fonts are embedded, so it looks identical on Windows and Mac;
   send the DOCX only if the IRB asks to edit it
5. Complete manual steps — Sign forms, attach protocol, email to [email protected]

Config Schema

study:
  irb_no: "20250801A"
  title_zh: "研究中文標題"
  title_en: "English Title"
  type: retrospective        # retrospective|prospective|clinical_trial
  review_type: expedited     # exempt|expedited|full_board

pi:
  name: "林協霆"
  dept: "腫瘤內科部／醫師"
  email: "[email protected]"

subjects:
  planned_n: 300
  consent_waiver: true       # auto-set for retrospective

phase: new                   # new|amendment|continuing|closure|sae|...

See config-schema reference for all fields.

Study Type → Form Selection

Testing

make test

27 tests covering form selection logic, DOCX content verification, checklist generation, end-to-end generation for both new case and closure phases, and the layout safety gate.

Dependencies

• Python 3.10+
• python-docx — DOCX generation
• PyYAML — Config parsing
• LibreOffice — DOCX→PDF conversion (brew install --cask libreoffice; Windows: winget install TheDocumentFoundation.LibreOffice; Linux: apt install libreoffice-writer fonts-arphic-ukai)
• poppler — PDF→PNG preview (brew install poppler)

Claude Code Integration

This project includes a Claude Code skill that enables AI-assisted IRB form preparation. When using Claude Code in this repo, it can:

• Classify your study type from a proposal description
• Auto-fill config.yml based on your study details
• Generate and validate all required forms
• Guide you through manual steps

Project Structure

irb-in-hurry/
├── config.yml                 # Study metadata (single source of truth)
├── Makefile                   # Easy commands
├── dashboard.sh               # Status overview
├── scripts/
│   ├── docx_utils.py          # Shared DOCX helpers
│   ├── form_selector.py       # 43-form registry + routing
│   ├── generate_all.py        # Main orchestrator
│   ├── checklist.py           # ■/□ checklist generator
│   ├── convert.py             # DOCX→PDF→PNG pipeline
│   ├── fetch_templates.py     # Download official blank forms
│   ├── validate_layout.py     # Layout/font safety gate
│   └── generators/            # One module per IRB category
│       ├── new_case.py        # SF001, SF002, SF094, SF011, SF022
│       ├── consent.py         # SF003-005, SF062, SF063, SF075, SF090-092
│       ├── closure.py         # SF036, SF037, SF038, SF023
│       ├── amendment.py       # SF014, SF015, SF016
│       ├── continuing_review.py # SF030, SF031, SF032
│       ├── sae.py             # SF079, SF044, SF074, SF080, SF024
│       ├── ib_update.py       # SF082, SF083, SF084, SF085
│       ├── import_forms.py    # SF066, SF067, SF068, SF093
│       ├── suspension.py      # SF047, SF048
│       ├── appeal.py          # SF077, SF054
│       ├── re_review.py       # SF019
│       └── other.py           # SF076
├── .claude/skills/irb/        # Claude Code skill set
├── tests/                     # pytest suite
└── output/                    # Generated files (gitignored)

FAQ

What is IRB-in-Hurry?
An open-source Python tool that fills in KFSYSCC Institutional Review Board (IRB) submission forms automatically from a single YAML config, producing Word (DOCX) and PDF files ready to sign.

Does it replace IRB review or ethical judgment?
No. It never submits, approves, or skips anything. It fills in the paperwork the IRB requires. Study design, risk assessment, and participant protection stay with you and the committee.

Which IRB submissions are supported?
All 11 KFSYSCC categories: new case (新案), re-review (複審), amendment (修正案), continuing review (期中審查), closure (結案), SAE (嚴重不良反應), IB update, project import, suspension, appeal (申覆), and other forms. That's 43 forms in total.

Will the forms look right on Windows and Mac?
Yes. Submit the generated PDF, which has fonts embedded. make validate checks A4 page size, official margins, and 標楷體 (DFKai-SB) usage against the official blank templates, and it has to report 0 errors before you submit.

Can I use it for another hospital's IRB?
The form registry and generators are KFSYSCC-specific, but the architecture (YAML → form selector → per-category generators → layout gate) is designed to be adapted. Fork it and swap in your institution's templates.

Does it work with AI assistants?
Yes. It includes a Claude Code skill that can classify your study from a proposal, draft config.yml, and walk you through the remaining manual steps.

References

• KFSYSCC IRB Forms — Official form downloads
• Nuremberg Code (1947) — Foundation of research ethics
• Declaration of Helsinki (1964) — Ethical principles for medical research
• The Belmont Report (1979) — Respect, Beneficence, Justice
• Common Rule (45 CFR 46) — U.S. federal regulations for human subjects research

License

MIT. Free to use, fork, and adapt for your own institution's IRB.

_{Made for researchers who'd rather be doing research. ⏱️ IRB-in-Hurry}