irb-form-generator

IRB-in-Hurry Skill

Automated KFSYSCC IRB form generation system. Generates DOCX forms from config.yml, converts to PDF/PNG for visual review.

Quick Start

Users do NOT need to manually edit YAML. Just provide any free-form text:

User: "我想做一個回溯性研究，看2018-2023年肺癌免疫治療的甲狀腺功能，大約200人。我是腫瘤內科陳雅文。"

Claude will:

1. Save raw text to raw/
2. Distill into config.yml (see distill.md)
3. Ask for any missing required fields (IRB number, dates)
4. Run make all + make review
5. Show dashboard and review opinions

Manual alternative

# If user prefers to edit YAML directly:
vim config.yml
make all
make review

Workflow Overview

When a user provides a study topic, proposal, or any text:

1. Save raw input -- Write to raw/proposal_YYYYMMDD.md
2. Distill to config -- Extract study type, PI, dates, subjects → config.yml (see distill.md)
3. Confirm with user -- Ask about any missing required fields (IRB number, exact dates)
4. Generate forms -- make all → DOCX + PDF + PNG previews + dashboard
5. Run reviewer -- make review → reviewers/review_*.md
6. Visual validation -- Read output/preview/*.png to verify layout
7. Fix findings -- Address required revisions from reviewer
8. Update checklist -- Track manual steps via checklist.md

Study Type Classification

Study Type	Review Type	Key Config Flags
Retrospective chart review	expedited	type: retrospective, consent_waiver: true
Prospective observational	expedited or full_board	type: prospective
Clinical trial (drug)	full_board	type: clinical_trial, drug_device: true
Clinical trial (device)	full_board	type: clinical_trial, drug_device: true
Genetic research	full_board	type: genetic, genetic: true
Multi-center study	varies	multicenter: true

See study-types.md for the full decision tree.

Phase to Forms Mapping

Phase	Forms	When
new	SF001, SF002, SF094 + conditional	Initial submission
amendment	SF014, SF015, SF016, SF094	Protocol changes
re_review	SF019	Responding to IRB queries
continuing	SF030, SF031, SF023	Annual review
closure	SF036, SF037, SF038, SF023	Study completion
sae	SF079, SF044/SF074, SF080, SF024	Adverse events
ib_update	SF082, SF083	Investigator's Brochure updates
import	SF066, SF067, SF068, SF093	Drug import
suspension	SF047, SF048	Study pause
appeal	SF077, SF054	Decision appeal

The form selector (scripts/form_selector.py) automatically adds conditional forms based on study type, review type, and config flags.

Config Schema (Key Fields)

study:
  irb_no: ""           # IRB case number
  title_zh: ""         # Chinese title
  title_en: ""         # English title
  type: ""             # retrospective | prospective | clinical_trial | genetic
  review_type: ""      # exempt | expedited | full_board
  drug_device: false   # Drug or device trial
  genetic: false       # Involves genetic data
  multicenter: false   # Multi-center study

pi:
  name: ""             # PI Chinese name
  dept: ""             # Department/title

dates:
  study_start: ""      # Study start date
  study_end: ""        # Study end date

subjects:
  planned_n: 0         # Planned enrollment
  consent_waiver: false # Waiver of informed consent

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

See config-schema.md for the complete field reference.

Checkbox Convention

• check(True) returns U+25A0 (filled square) = checked/yes
• check(False) returns U+25A1 (empty square) = unchecked/no

All forms use this convention via docx_utils.check().

Project Structure

config.yml                     # Study metadata (single source of truth)
scripts/
  docx_utils.py               # Shared DOCX helpers (init_doc, add_p, add_ct, etc.)
  form_selector.py            # Phase + study type -> required forms
  generate_all.py             # Main orchestrator
  checklist.py                # Generates checklist.md with status
  convert.py                  # DOCX -> PDF -> PNG pipeline
  generators/
    new_case.py               # SF001, SF002, SF094, SF011, SF022
    closure.py                # SF036, SF037, SF038, SF023
    consent.py                # SF003, SF004, SF005, SF062, SF063, SF075, SF090-092
    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
output/                        # Generated DOCX and PDF files
output/preview/                # PNG previews for visual validation
checklist.md                   # Auto-generated submission checklist
dashboard.sh                   # Terminal status dashboard

Form Details by Category

• New Case (New Case Review) -- SF001, SF002, SF094, SF003-005
• Closure (Closure Review) -- SF036, SF037, SF038, SF023
• Amendment (Amendment Review) -- SF014, SF015, SF016
• Continuing Review (Interim Review) -- SF030, SF031, SF032
• SAE & Non-compliance (Serious Adverse Event) -- SF079, SF044, SF074, SF080, SF024
• Other Categories -- IB update, import, suspension, appeal
• Study Types & Routing -- Classification logic
• Config Schema -- All config.yml fields
• Brainstorm -- Research topic ideas tailored to KFSYSCC + Taiwan epidemiology
• Distill: Raw Text → Config -- How to extract config from free-form text
• Reviewer Criteria -- Simulated IRB review checklist
• Reviewer Guide -- Rules of thumb, red flags, 45 CFR 46.111 training

Validation

After generating forms:

1. Run python scripts/convert.py to create PDFs and PNG previews
2. Read each output/preview/*.png to visually verify layout and content
3. Check checklist.md for remaining manual steps (signatures, content sections)
4. Run ./dashboard.sh for terminal status overview

Adding New Generators

Each generator function follows this signature:

def generate_sfXXX(config: dict, output_dir: str) -> str:
    """Generate SFXXX form. Returns output file path."""
    doc = init_doc()
    # ... build document ...
    path = os.path.join(output_dir, "SFXXX_中文名稱.docx")
    doc.save(path)
    return path

Register in FORM_REGISTRY in scripts/form_selector.py, then add to the appropriate phase in PHASE_FORMS.

Submission

• Electronic: email to irb@kfsyscc.org
• Paper: 1 original + 1 copy to IRB office (B1 administrative building)
• Signed forms require PI wet signature before submission