@bgicli/bgicli 2.1.1 → 2.2.0

package/data/skills/clinical-trial-protocol-skill/SKILL.md

@@ -0,0 +1,508 @@
+---
+name: clinical-trial-protocol-skill
+description: Generate clinical trial protocols for medical devices or drugs. This skill should be used when users say "Create a clinical trial protocol", "Generate protocol for [device/drug]", "Help me design a clinical study", "Research similar trials for [intervention]", or when developing FDA submission documentation for investigational products.
+---
+
+# Clinical Trial Protocol Skill
+
+## ⚠️ EXECUTION CONTROL - READ THIS FIRST
+
+**CRITICAL: This orchestrator follows a SIMPLE START approach:**
+
+1. **Display the welcome message FIRST** (shown in "Startup: Welcome and Confirmation" section below)
+2. **Ask user to confirm they're ready to proceed** - Wait for confirmation (yes/no)
+3. **Jump directly into Full Workflow Logic** - Automatically run subskills sequentially
+4. **Do NOT pre-read subskill files** - Subskills are loaded on-demand only when their step executes
+
+**Why this matters:**
+- Pre-reading all subskills wastes context and memory
+- Subskills should only load when actually needed during execution
+- Workflow automatically handles resuming from existing waypoints
+
+## Overview
+
+This skill generates clinical trial protocols for **medical devices or drugs** using a **modular, waypoint-based architecture** 
+
+## What This Skill Does
+
+Starting with an intervention idea (device or drug), this orchestrated workflow offers two modes:
+
+**🔬 Research Only Mode (Steps 0-1):**
+0. **Initialize Intervention** - Collect device or drug information
+1. **Research Similar Protocols** - Find similar trials, FDA guidance, and published protocols
+   - **Deliverable:** Comprehensive research summary as formatted .md artifact
+
+**📄 Full Protocol Mode (Steps 0-5):**
+0. **Initialize Intervention** - Collect device or drug information
+1. **Research Similar Protocols** - Find similar trials, FDA guidance, and published protocols
+2. **Protocol Foundation** - Generate protocol sections 1-6 (foundation, design, population)
+3. **Protocol Intervention** - Generate protocol sections 7-8 (intervention details)
+4. **Protocol Operations** - Generate protocol sections 9-12 (assessments, statistics, operations)
+5. **Generate Protocol** - Create professional file ready for stakeholder review
+
+## Architecture
+
+### Waypoint-Based Design
+
+All analysis data is stored in `waypoints/` directory as JSON/markdown files:
+
+```
+waypoints/
+├── intervention_metadata.json           # Intervention info, status, initial context
+├── 01_clinical_research_summary.json   # Similar trials, FDA guidance, recommendations
+├── 02_protocol_foundation.md            # Protocol sections 1-6 (Step 2)
+├── 03_protocol_intervention.md          # Protocol sections 7-8 (Step 3)
+├── 04_protocol_operations.md            # Protocol sections 9-12 (Step 4)
+├── 02_protocol_draft.md                 # Complete protocol (concatenated in Step 4)
+├── 02_protocol_metadata.json            # Protocol metadata
+└── 02_sample_size_calculation.json      # Statistical sample size calculation
+```
+
+**Rich Initial Context Support:**
+Users can provide substantial documentation, technical specifications, or research data when initializing the intervention (Step 0). This is preserved in `intervention_metadata.json` under the `initial_context` field. Later steps reference this context for more informed protocol development.
+
+### Modular Subskill Steps
+
+Each step is an independent skill in `references/` directory:
+
+```
+references/
+├── 00-initialize-intervention.md    # Collect device or drug information
+├── 01-research-protocols.md         # Clinical trials research and FDA guidance
+├── 02-protocol-foundation.md        # Protocol sections 1-6 (foundation, design, population)
+├── 03-protocol-intervention.md      # Protocol sections 7-8 (intervention details)
+├── 04-protocol-operations.md        # Protocol sections 9-12 (assessments, statistics, operations)
+└── 05-generate-document.md          # NIH Protocol generation
+```
+
+### Utility Scripts
+
+```
+scripts/
+└── sample_size_calculator.py   # Statistical power analysis (validated)
+```
+
+## Prerequisites
+
+### 1. clinical trials MCP Server (Required)
+
+**Installation:**
+- Install via drag-and-drop `.mcpb` file into Claude Desktop
+- Or configure manually in Claude Desktop settings
+
+**Available Tools:**
+`search_clinical_trials` - Search by:
+
+condition - Disease or condition (e.g., "pancreatic cancer")
+intervention - Drug, device, or treatment (e.g., "pembrolizumab", "CAR-T")
+sponsor - Sponsor or collaborator name (e.g., "Pfizer", "NIH")
+location - City, state, or country (e.g., "California", "Boston")
+status - "recruiting" (default), "active", "completed", "all"
+phase - Trial phase: "1", "2", "3", "4", "early_phase1"
+max_results - Default 25, max 100
+
+
+`get_trial_details` - Get comprehensive details for a specific trial using its nct_id (e.g., "NCT04267848"). Returns eligibility criteria, outcomes, study design, and contact information.
+
+**Verification:** Step 1 will automatically test MCP connectivity at startup.
+
+### 2. FDA Database Access (Built-in)
+
+**Purpose:** FDA regulatory pathway research via explicit database URLs
+
+**Sources:**
+- Step 1: FDA device/drug databases (510(k), PMA, De Novo, Drugs@FDA, Orange Book, Purple Book)
+- All sources use direct FDA database URLs - no generic web searches
+
+### 3. Clinical Protocol Template
+
+**Template Files:** Any `.md` files in the `assets/` directory
+
+**Purpose:** Reference template for protocol structure and content guidance. The system automatically detects available templates and uses them dynamically.
+
+### 4. Python Dependencies (Required for Step 2)
+
+**Installation:**
+```bash
+pip install -r requirements.txt
+```
+
+**Dependencies:**
+- scipy >= 1.11.0 (statistical calculations)
+- numpy >= 1.24.0 (numerical operations)
+
+**Purpose:** Accurate statistical sample size calculations for clinical protocols
+
+## How to Use
+
+Simply invoke the skill and select your desired mode:
+
+**🔬 Research Only Mode:**
+1. Select "Research Only" from the main menu
+2. Provide intervention information
+3. Receive comprehensive research summary as formatted .md artifact
+4. Option to continue with full protocol generation or exit
+
+**📄 Full Protocol Mode:**
+1. Select "Full Protocol" from the main menu
+2. Guide you through all steps sequentially (Steps 0-5)
+3. Pause after Step 4 to review the draft protocol
+4. Generate the final protocol document when ready
+
+**Resume Capability:** If interrupted, simply restart the skill and it will automatically resume from your last completed step.
+
+## Execution Flow
+
+### Startup: Welcome and Mode Selection
+
+When skill is invoked, display the following message:
+
+```
+🧬 CLINICAL TRIAL PROTOCOL
+
+Welcome! This skill generates clinical trial protocols for medical devices or drugs.
+
+[If waypoints/intervention_metadata.json exists:]
+✓ Found existing protocol in progress: [Intervention Name]
+  Type: [Device/Drug]
+  Completed: [List of completed steps]
+  Next: [Next step to execute]
+
+📋 SELECT MODE:
+
+1. 🔬 Research Only - Run clinical research analysis (Steps 0-1)
+   • Collect intervention information
+   • Research similar clinical trials
+   • Find FDA guidance and regulatory pathways
+   • Generate comprehensive research summary as .md artifact
+
+2. 📄 Full Protocol - Generate complete clinical trial protocol (Steps 0-5)
+   • Everything in Research Only, plus:
+   • Generate all protocol sections
+   • Create professional protocol document
+
+3. ❌ Exit
+
+Please select an option (1, 2, or 3):
+```
+
+**🛑 STOP and WAIT for user selection (1, 2, or 3)**
+
+- If **1 (Research Only)**: Set `execution_mode = "research_only"` and proceed to Research Only Workflow Logic
+- If **2 (Full Protocol)**: Set `execution_mode = "full_protocol"` and proceed to Full Workflow Logic
+- If **3 (Exit)**: Exit gracefully with "No problem! Restart the skill anytime to continue."
+
+---
+
+### Research Only Workflow Logic
+
+**This workflow executes only Steps 0 and 1, then generates a formatted research summary artifact.**
+
+**Step 1: Check for Existing Waypoints**
+- If `waypoints/intervention_metadata.json` exists: Load metadata, check if steps 0 and 1 are already complete
+- If no metadata exists: Start from Step 0
+
+**Step 2: Execute Research Steps (0 and 1)**
+
+For each step (0, 1):
+
+1. **Check completion status:** If step already completed in metadata, skip with "✓ Step [X] already complete"
+
+2. **Execute step:**
+   - Display "▶ Executing Step [X]..."
+   - Read and follow the corresponding subskill file instructions
+   - Wait for completion
+   - Display "✓ Step [X] complete"
+   - **Step execution method (ON-DEMAND LOADING):** When a step is ready to execute (NOT before), read the subskill markdown file and execute ALL instructions within it
+   - **Step-to-file mapping:**
+     - Step 0: `references/00-initialize-intervention.md` (collect intervention info)
+     - Step 1: `references/01-research-protocols.md` (clinical research and FDA guidance)
+
+3. **Handle errors:** If step fails, ask user to retry or exit. Save current state for resume capability.
+
+**Step 3: Generate Research Summary Artifact**
+
+After Step 1 completes successfully:
+
+1. **Read waypoint files:**
+   - `waypoints/intervention_metadata.json` (intervention details)
+   - `waypoints/01_clinical_research_summary.json` (research findings)
+
+2. **Create formatted markdown summary:** Generate a comprehensive, well-formatted research summary as a markdown artifact with the following structure:
+
+```markdown
+# Clinical Research Summary: [Intervention Name]
+
+## Intervention Overview
+- **Type:** [Device/Drug]
+- **Indication:** [Target condition/disease]
+- **Description:** [Brief intervention description]
+- **Mechanism of Action:** [How it works]
+
+## Similar Clinical Trials
+[List top 5-10 similar trials with NCT ID, title, phase, status, key findings]
+
+## FDA Regulatory Pathway
+- **Recommended Pathway:** [510(k), PMA, De Novo, IND, NDA, BLA, etc.]
+- **Regulatory Basis:** [Rationale for pathway selection]
+- **Key Requirements:** [Major regulatory considerations]
+
+## FDA Guidance Documents
+[List relevant FDA guidance documents with links and key excerpts]
+
+## Study Design Recommendations
+- **Suggested Study Type:** [RCT, single-arm, etc.]
+- **Phase Recommendation:** [Phase 1, 2, 3, etc.]
+- **Primary Endpoint Suggestions:** [Based on similar trials]
+- **Sample Size Considerations:** [Preliminary thoughts]
+
+## Key Insights and Recommendations
+[Synthesized recommendations for protocol development]
+
+## Next Steps
+[If user wants to proceed with full protocol development]
+
+---
+*Generated by Clinical Trial Protocol Skill*
+*Date: [Current date]*
+```
+
+3. **Save artifact:** Write the formatted summary to `waypoints/research_summary.md`
+
+4. **Display completion message:**
+
+```
+✅ RESEARCH COMPLETE
+
+Research Summary Generated: waypoints/research_summary.md
+
+📊 Key Findings:
+  • Similar Trials Found: [X trials]
+  • Recommended Pathway: [Pathway name]
+  • FDA Guidance Documents: [X documents identified]
+  • Study Design: [Recommended design]
+
+📄 The research summary has been saved as a formatted markdown artifact.
+
+Would you like to:
+1. Continue with full protocol generation (steps 2-5)
+2. Exit and review research summary
+
+```
+
+**Option 1 Logic (Continue to Full Protocol):**
+- Set `execution_mode = "full_protocol"`
+- Continue to Full Workflow Logic starting from Step 2 (since 0 and 1 are complete)
+
+**Option 2 Logic (Exit):**
+- Display: "✓ Research summary saved. Restart the skill anytime to continue with protocol generation."
+- Exit orchestrator gracefully
+
+---
+
+### Full Workflow Logic
+
+**Step 1: Check for Existing Waypoints**
+- If `waypoints/intervention_metadata.json` exists: Load metadata, check `completed_steps` array, resume from next incomplete step
+- If no metadata exists: Start from Step 0
+
+**Step 2: Execute Steps in Order**
+
+For each step (0, 1, 2, 3, 4, 5):
+
+1. **Check completion status:** If step already completed in metadata, skip with "✓ Step [X] already complete"
+
+2. **Execute step:** Display "▶ Executing Step [X]...", read and follow the corresponding subskill file instructions, wait for completion, display "✓ Step [X] complete"
+   - **Step execution method (ON-DEMAND LOADING):** When a step is ready to execute (NOT before), read the subskill markdown file and execute ALL instructions within it
+   - **IMPORTANT:** Do NOT read subskill files in advance. Only read them at the moment of execution.
+   - **Step-to-file mapping:**
+     - Step 0: `references/00-initialize-intervention.md` (read when Step 0 executes)
+     - Step 1: `references/01-research-protocols.md` (read when Step 1 executes)
+     - Step 2: `references/02-protocol-foundation.md` (read when Step 2 executes - sections 1-6)
+     - Step 3: `references/03-protocol-intervention.md` (read when Step 3 executes - sections 7-8)
+     - Step 4: `references/04-protocol-operations.md` (read when Step 4 executes - sections 9-12)
+     - Step 5: `references/05-concatenate-protocol.md` (read when Step 5 executes - final concatenation)
+
+3. **Handle errors:** If step fails, ask user to retry or exit. Save current state for resume capability.
+
+4. **Display progress:** "Progress: [X/6] steps complete", show estimated remaining time
+
+5. **Step 4 Completion Pause:** After Step 4 completes, pause and display the Protocol Completion Menu (see below). Wait for user selection before proceeding.
+
+**Step 2.5: Protocol Completion Menu**
+
+After Step 4 completes successfully, display the EXACT menu below (do not improvise or create alternative options):
+
+```
+✅ PROTOCOL COMPLETE: Protocol Draft Generated
+
+Protocol Details:
+  • Study Design: [Design from metadata]
+  • Sample Size: [N subjects from metadata]
+  • Primary Endpoint: [Endpoint from metadata]
+  • Study Duration: [Duration from metadata]
+
+Protocol file: waypoints/02_protocol_draft.md
+File size: [Size in KB]
+
+📋 WHAT WOULD YOU LIKE TO DO NEXT?
+
+1. 📄 Review Protocol in Artifact - click on the .md file above
+
+2. 📄 Concatenate Final Protocol (Step 5)
+
+3. ⏸️  Exit and Review Later
+
+```
+
+**Option 1 Logic (Review in Artifact):**
+Pause, let user open the section files, wait for further instruction
+
+**Option 2 Logic (Concatenate Protocol):**
+1. Execute Step 5 by reading and following `references/05-concatenate-protocol.md`
+2. Step 5 will concatenate all section files into final protocol document
+3. Continue to Step 3 (Final Summary) after Step 5 completes
+
+**Option 3 Logic (Exit):**
+1. Display: "✓ Protocol sections saved. You can resume with Step 5 anytime to concatenate."
+2. Exit orchestrator gracefully
+
+**Step 3: Final Summary**
+
+Display completion message with:
+- Intervention name, type (device/drug), indication
+- Protocol details (design, sample size, endpoints, duration)
+- All completed steps list
+- Final deliverable: Complete protocol markdown file location (waypoints/protocol_complete.md)
+- Waypoint files list for reference
+- Important disclaimers (FDA Pre-Sub, biostatistician review, IRB approval required)
+- Thank you message
+
+## Technical Details
+
+### Waypoint File Formats
+
+**JSON Waypoints** (Steps 0, 1):
+- Structured data for programmatic access
+- Small file sizes (1-15KB)
+- Easy to parse and reference
+
+**Markdown Waypoints** (Steps 2, 3, 4):
+- Step 2: `02_protocol_foundation.md` (Sections 1-6)
+- Step 3: `03_protocol_intervention.md` (Sections 7-8)
+- Step 4: `04_protocol_operations.md` (Sections 9-12)
+- Step 4: `02_protocol_draft.md` (concatenated complete protocol)
+- Human-readable protocol documents
+- Can be directly edited by users
+- Individual section files preserved for easier regeneration
+
+### Data Minimization Strategy
+
+Each step implements aggressive summarization:
+- **Keep:** Top-N results (5-10 max)
+- **Keep:** Key facts and IDs (NCT numbers, endpoint types)
+- **Keep:** Concise rationale (2-3 sentences)
+- **Discard:** Raw MCP query results (not needed after analysis)
+- **Discard:** Full FDA guidance text (only excerpts/citations kept)
+- **Discard:** Lower-ranked search results
+
+### Step Independence
+
+Each subskill is designed to:
+- Read only from waypoint files (not conversation history)
+- Produce complete output in single execution
+- Not depend on conversation context from previous steps
+- Be runnable standalone
+
+## Error Handling
+
+### MCP Server Unavailable
+- Detected in: Step 1
+- Action: Display error with installation instructions
+- Allow user to retry after installing MCP server
+- No fallback available - MCP server is required for protocol research
+
+### Step Fails or Returns Error
+- Action: Display error message from subskill
+- Ask user: "Retry step? (Yes/No)"
+  - Yes: Re-run step
+  - No: Save current state, exit orchestrator
+
+### User Interruption
+- All progress saved in waypoint files
+- User can resume anytime by restarting the skill
+- Workflow automatically detects completed steps and resumes from next step
+- No data loss
+
+## Disclaimers
+
+⚠️ **IMPORTANT:** This protocol generation tool provides preliminary clinical study protocol based on NIH/FDA guidelines and similar trials. It does NOT constitute:
+- Official FDA or IRB determination or approval
+- Medical, legal, or regulatory advice
+- Substitute for professional biostatistician review
+- Substitute for FDA Pre-Submission meeting
+- Guarantee of regulatory or clinical success
+
+**REQUIRED before proceeding with clinical study:**
+- Biostatistician review and sample size validation
+- FDA Pre-Submission meeting (Q-Submission for devices, Pre-IND for drugs)
+- IRB review and approval
+- Clinical expert and regulatory consultant engagement
+- Legal review of protocol and informed consent
+- Site investigator review and input
+- Sponsor completion of all [TBD] items in protocol
+
+**PROFESSIONAL CONSULTATION STRONGLY RECOMMENDED**
+
+Clinical trial protocols are complex, high-stakes documents requiring expertise across multiple disciplines. Professional consultation with clinical trial experts, biostatisticians, and regulatory affairs specialists is essential before proceeding with clinical study planning.
+
+
+## Implementation Requirements
+
+When this skill is invoked:
+
+1. **Display the welcome message with mode selection** (shown in "Startup: Welcome and Mode Selection" section)
+
+2. **Wait for user mode selection** (1: Research Only, 2: Full Protocol, 3: Exit)
+
+3. **Execute based on selected mode:**
+   - **Research Only Mode (Option 1):**
+     - Execute Research Only Workflow Logic (Steps 0-1 only)
+     - Generate formatted research summary as .md artifact
+     - Offer option to continue with full protocol or exit
+   - **Full Protocol Mode (Option 2):**
+     - Execute Full Workflow Logic (Steps 0-5)
+     - Check for existing waypoints and resume from last completed step
+     - OR start from Step 0 if no waypoints exist
+     - Execute all steps sequentially until complete
+
+4. **For each step execution (LAZY LOADING - On-Demand Only):**
+   - **ONLY when a step is ready to execute**, read the corresponding subskill file
+   - Do NOT read subskill files in advance or "to prepare"
+   - Example: When Step 1 needs to run, THEN read `references/01-research-protocols.md` and follow its instructions
+   - **For protocol development:** Execute Steps 2, 3, 4 sequentially in order
+   - Do NOT try to execute multiple steps in parallel - run sequentially
+   - Read each step's subskill file only when that specific step is about to execute
+
+5. **Research summary artifact generation (Research Only Mode):**
+   - After Step 1 completes, read waypoint files
+   - Generate comprehensive, well-formatted markdown summary
+   - Save to `waypoints/research_summary.md`
+   - Display completion message with key findings
+
+6. **Handle errors gracefully:**
+   - If a step fails, give user option to retry or exit
+   - If MCP server unavailable, explain how to install
+   - All progress is saved automatically in waypoints
+
+7. **Track progress:**
+   - Update `waypoints/intervention_metadata.json` after each step
+   - Show progress indicators to user (e.g., "Progress: 3/6 steps complete" or "Progress: 2/2 research steps complete")
+   - Provide clear feedback on what's happening
+
+8. **Final output:**
+   - **Research Only:** Display research summary location and offer to continue with full protocol
+   - **Full Protocol:** Congratulate user, display protocol location and next steps
+   - Remind user of disclaimers
+
+