IRB-in-Hurry Skill

Institution-agnostic IRB form pipeline: plain-text study sources (config.toml + referenced cv.toml / 中文計畫摘要.md) + an institution profile (institutions/<id>/) → official DOCX forms → PDF/PNG → layout gate. KFSYSCC (irb_in_hurry/institutions/kfsyscc/, 43 forms) is the reference pack.

Running it

Everything runs through the irbh command, in the study folder (the one holding config.toml). If irbh is not on PATH, use uvx --from irb-in-hurry irbh … (or uv tool install irb-in-hurry once; from GitHub: uv tool install git+https://github.com/htlin222/irb-in-hurry); inside a checkout of the irb-in-hurry repo, uv run irbh … (or the matching make target) does the same. irbh doctor reports what is missing (LibreOffice, poppler, form font, blanks).

Step 0: Which institution?

Before anything else, settle which committee the user is submitting to:

Everything institution-specific (committee name, IRB-number label, submission email, paper size, margins, font, form list, routing) comes from the pack's profile.toml + forms.py. Never hardcode these in code or generators: read institution() (from irb_in_hurry.docx_utils). Method and invariants: docs/METHODOLOGY.md.

Quick Start

Users do NOT need to edit config files by hand. Just provide any free-form text:

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

Claude will:

1. Save raw text to raw/
2. Distill into config.toml + cv.toml + 中文計畫摘要.md (see distill.md); run irbh check
3. Ask for any missing required fields (IRB number, dates)
4. Run irbh all + irbh review
5. Show dashboard and review opinions

Manual alternative

# If user prefers to edit the sources directly:
irbh init tdxd-her2low   # optional starting point
vim config.toml cv.toml 中文計畫摘要.md
irbh check && irbh all
irbh 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 -- Study type, dates, subjects → config.toml; PI/co-PI → cv.toml; background/objectives/methods prose → 中文計畫摘要.md (see distill.md). irbh check must pass
3. Confirm with user -- Ask about any missing required fields (IRB number, exact dates)
4. Generate forms -- irbh all → DOCX + PDF + PNG previews + dashboard
5. Run reviewer -- irbh review → reviewers/review_*.md
6. Layout safety gate -- irbh validate (part of irbh all; run irbh templates once first). Must be 0 errors. Read output/layout_report.md, then view output/preview/compare/*.png (official blank left, generated right) and report any visible drift to the user. Remind the user to submit the PDF (fonts embedded → identical on Windows/Mac).
7. Fix findings -- Address required revisions from reviewer
8. Update checklist -- Track manual steps via checklist.md

Study Type Classification (generic)

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

Phase to Forms Mapping (KFSYSCC pack)

Phase names are generic; the forms per phase come from the active institution's PHASE_FORMS. For KFSYSCC:

The form selector (irb_in_hurry/form_selector.py) reads the active institution's forms_module and adds conditional forms based on study type, review type, and config flags.

Config Schema (Key Fields)

# config.toml — "@file" / "@file#key" values are replaced by that file's content
institution = "kfsyscc"        # institution pack id (`irbh institutions`)
phase    = "new"               # new | amendment | continuing | closure | sae | ...
pi       = "@cv.toml#pi"       # [pi] name, name_en, dept, phone, email
co_pi    = "@cv.toml#co_pi"    # [[co_pi]] entries (optional)
proposal = "@中文計畫摘要.md"   # ## 研究背景 / 研究目的 / 納入條件 / 統計分析 ...

[study]
irb_no      = ""               # IRB case number (blank until assigned)
title_zh    = ""
title_en    = ""
type        = "retrospective"  # retrospective | prospective | clinical_trial | genetic
review_type = "expedited"      # exempt | expedited | full_board
drug_device = false
genetic     = false
multicenter = false

[dates]
study_start = ""
study_end   = ""

[subjects]
planned_n      = 0
consent_waiver = false

Phase switches never re-dump the file: irbh closure == irbh all --phase closure (one-off); irbh set-phase closure persists it by editing only the phase = line.

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

Study folder (where irbh runs):

config.toml                    # Study metadata (single source of truth) + `institution`
cv.toml                        # Study team (@cv.toml#pi, @cv.toml#co_pi)
中文計畫摘要.md                 # Proposal prose (@中文計畫摘要.md)
institutions/<id>/             # (optional) a local pack, written by `irbh onboard <id>`
  profile.toml                 # names, labels, submission, page, font, blanks
  forms.py                     # FORM_REGISTRY + PHASE_FORMS (form pack)
  form_inventory.md            # (onboarded packs) what each blank contains
templates/<id>/                # official blank forms (gitignored ground truth; $IRB_TEMPLATES to share)
output/                        # Generated DOCX and PDF files
output/preview/                # PNG previews for visual validation
checklist.md                   # Auto-generated submission checklist

Packs are found local institutions/<id>/ → installed (irb_in_hurry.institutions entry point) → bundled. The package itself:

irb_in_hurry/
  cli.py                      # `irbh` command
  dashboard.py                # Terminal status dashboard (`irbh dashboard`)
  examples/                   # Complete example studies (`irbh init <name>`)
  institutions/kfsyscc/       # Bundled reference pack
  institution.py              # active profile loader
  config.py                   # config.toml loader: @references, Markdown, validation (ConfigError lists every problem)
  template_fill.py            # generic fill-the-blank generator
  onboard.py                  # blanks → draft profile/forms/inventory
  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 (--phase, --output, --verbose)
  set_phase.py                # Persist phase in config.toml, keeping comments
  checklist.py                # Generates checklist.md with status
  convert.py                  # DOCX -> PDF -> PNG pipeline
  generators/                 # KFSYSCC rebuild generators (reference pack)
    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

Form Details by Category (KFSYSCC pack)

• New Case (新案審查) -- SF001, SF002, SF094, SF003-005
• Closure (結案審查) -- SF036, SF037, SF038, SF023
• Amendment (修正案審查) -- SF014, SF015, SF016
• Continuing Review (期中審查) -- SF030, SF031, SF032
• SAE & Non-compliance (嚴重不良反應) -- SF079, SF044, SF074, SF080, SF024
• Other Categories -- IB update, import, suspension, appeal
• Study Types & Routing -- Classification logic
• Config Schema -- All config.toml fields and @ references
• Onboard an Institution -- New committee from its blank DOCX forms
• Brainstorm -- Research topic ideas (KFSYSCC + Taiwan epidemiology example)
• 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 irbh pdf to create PDFs and PNG previews (part of irbh all)
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 irbh dashboard for terminal status overview

Adding New Generators

Prefer filling the official blank (layout-exact, a few lines per form):

# institutions/<id>/forms.py
from irb_in_hurry.template_fill import blank_generator

generate_f01 = blank_generator("F01", fields={
    "計畫名稱": "{study.title_zh}",          # label in the blank → config format string
    "預計收案人數": lambda c: f"{c['subjects']['planned_n']} 人",
}, checks={
    "簡易審查": lambda c: c["study"]["review_type"] == "expedited",
})

FORM_REGISTRY = {"F01": ("新案申請書", "institutions.<id>.forms", "generate_f01")}

Rebuild with python-docx only when a blank can't be filled (text boxes, content controls, PDF-only, generated prose):

def generate_sfXXX(config: dict, output_dir: str) -> str:
    doc = init_doc()                                  # profile page setup + font
    add_p(doc, institution().heading, bold=True)      # never a literal hospital name
    add_header(doc, config)                           # uses institution().irb_no_label
    path = os.path.join(output_dir, f"SFXXX_{config['study']['irb_no']}.docx")
    doc.save(path)
    return path

Register it in the institution's FORM_REGISTRY. A generators.* module path means the shared irb_in_hurry.generators; anything else is an absolute module (institutions.<id>.forms for a local pack). Then add it to PHASE_FORMS.

Submission

Read it from the profile (submission: block). checklist.md lists it. For KFSYSCC: email irb@kfsyscc.org; 1 original + 1 copy to the IRB office (B1 administrative building); PI wet signature on signed forms.