clinical-trial-protocol-skill

What this skill does

# 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].