@yeyuan98/opencode-bioresearcher-plugin 1.5.0 → 1.5.2-alpha.2

package/dist/skills/bioresearcher-core/patterns/bioresearcher/tool-selection.md

@@ -0,0 +1,481 @@
+# Tool Selection Decision Framework
+
+Comprehensive decision trees for choosing the correct tool based on user intent and data source.
+
+## Overview
+
+This pattern guides intelligent tool selection across 7 tool categories:
+1. Database Tools (db*)
+2. Table Tools (table*)
+3. Web Tools (web*)
+4. BioMCP Tools (biomcp*)
+5. Parser Tools (parse*)
+6. Miscellaneous Tools
+7. Core File Tools
+
+---
+
+## 1. Data Source Identification
+
+```
+USER INTENT ANALYSIS:
+├─ "Query database" / "SQL" / "table in database"
+│  → DATABASE TOOLS (db*)
+│
+├─ "Excel file" / "CSV file" / "table file" / "xlsx" / "spreadsheet"
+│  → TABLE TOOLS (table*)
+│
+├─ "website" / "web page" / "URL" / "fetch from"
+│  → WEB TOOLS (web*)
+│
+├─ "PubMed" / "articles" / "literature" / "papers" / "publications"
+│  → BIOMCP ARTICLE TOOLS
+│
+├─ "clinical trial" / "NCT" / "trial data"
+│  → BIOMCP TRIAL TOOLS
+│
+├─ "gene" / "variant" / "mutation" / "genomic"
+│  → BIOMCP GENE/VARIANT TOOLS
+│
+├─ "drug" / "compound" / "FDA" / "medication"
+│  → BIOMCP DRUG/FDA TOOLS
+│
+├─ "parse" / "convert" / "XML" / "OBO" / "ontology"
+│  → PARSER TOOLS (parse*)
+│
+└─ Unclear intent
+   → ASK user for clarification via question tool
+```
+
+---
+
+## 2. Database Tools Decision Tree
+
+### When to Use
+- User mentions database, SQL, or structured query
+- Need to query relational or document database
+- Data exists in MySQL or MongoDB
+
+### Workflow
+
+```
+IF user mentions database/SQL:
+  
+  Step 1: Check Configuration
+    IF env.jsonc does NOT exist:
+      → Load skill 'env-jsonc-setup'
+      → Follow skill workflow to configure database
+  
+  Step 2: Discover Available Data
+    dbListTables() → Show all tables to user
+    → Identify relevant tables
+  
+  Step 3: Understand Schema
+    dbDescribeTable(table_name) → Get column structure
+    → Identify available fields, data types, keys
+  
+  Step 4: Query with Filters (BEST PRACTICE)
+    ✅ DO: dbQuery(
+        "SELECT * FROM trials WHERE phase = :phase AND status = :status",
+        {phase: "Phase 3", status: "Recruiting"}
+      )
+    
+    ❌ DON'T: dbQuery("SELECT * FROM trials")
+              → then filter in Python
+  
+  Step 5: Use Named Parameters (SAFETY)
+    - NEVER concatenate SQL strings
+    - ALWAYS use :paramName syntax
+    - Pass parameters as second argument
+```
+
+### Example: Database Research Workflow
+
+```markdown
+User: "Find all Phase 3 melanoma trials from the database"
+
+Agent actions:
+1. dbListTables() → See available tables
+2. dbDescribeTable("clinical_trials") → Understand schema
+3. dbQuery(
+     "SELECT * FROM clinical_trials 
+      WHERE phase = :phase 
+        AND condition LIKE :condition
+        AND status = :status",
+     {
+       phase: "Phase 3",
+       condition: "%melanoma%",
+       status: "Recruiting"
+     }
+   )
+4. Return filtered results with proper citations
+```
+
+### Tool Reference
+
+| Tool | Purpose | When to Use |
+|------|---------|-------------|
+| `dbListTables` | List all tables/collections | Initial discovery |
+| `dbDescribeTable` | Get column schema | Before querying |
+| `dbQuery` | Execute SELECT query | Data retrieval |
+
+---
+
+## 3. Table Tools Decision Tree
+
+### When to Use
+- User provides Excel (.xlsx), CSV, or ODS file
+- Need to analyze, filter, or transform tabular data
+- Data exists in local file system
+
+### Row Count Decision Matrix
+
+```
+IF rows < 30:
+  → Use table tools directly (fastest)
+     - tableFilterRows() for filtering
+     - tableGroupBy() for aggregation
+     - tableSummarize() for statistics
+     - tablePivotSummary() for cross-tabs
+
+IF rows >= 30 AND rows < 1000:
+  → Decision based on complexity:
+     IF need structured summarization with JSON schema:
+       → Load skill 'long-table-summary'
+     ELSE:
+       → Use table tools directly
+
+IF rows >= 1000:
+  → Decision based on complexity:
+     IF need structured summarization:
+       → Load skill 'long-table-summary'
+     ELSE IF need complex transformations:
+       → Write custom Python script
+     ELSE:
+       → Use table tools with targeted operations
+```
+
+### Workflow
+
+```
+IF user provides Excel/CSV file:
+  
+  Step 1: Preview Structure
+    tableListSheets(file_path) → See available sheets
+    tableGetSheetPreview(file_path) → First 6 rows
+    tableGetHeaders(file_path) → Column names
+  
+  Step 2: Determine Row Count
+    tableGetRange(file_path, range="A1:A10000")
+    → Count non-empty rows
+  
+  Step 3: Choose Analysis Approach (see decision matrix above)
+  
+  Step 4: Apply Upfront Filtering (BEST PRACTICE)
+    ✅ DO: tableFilterRows(
+        file_path,
+        column="Status",
+        operator="=",
+        value="Active"
+      )
+    
+    ❌ DON'T: Load entire table then filter in Python
+```
+
+### Upfront Filtering Examples
+
+```markdown
+# Filter by single condition
+tableFilterRows(file, column="Phase", operator="=", value="Phase 3")
+
+# Filter by numeric range
+tableFilterRows(file, column="Age", operator=">=", value=18)
+
+# Filter by text contains
+tableFilterRows(file, column="Condition", operator="contains", value="melanoma")
+```
+
+### Tool Reference
+
+| Tool | Purpose | When to Use |
+|------|---------|-------------|
+| `tableListSheets` | List worksheet names | Multi-sheet workbooks |
+| `tableGetSheetPreview` | Preview first 6 rows | Understand structure |
+| `tableGetHeaders` | Get column names | Identify available fields |
+| `tableFilterRows` | Filter by condition | Extract subsets |
+| `tableSearch` | Search across all cells | Find specific values |
+| `tableSummarize` | Statistical summary | Numeric analysis |
+| `tableGroupBy` | Group and aggregate | Categorical analysis |
+| `tablePivotSummary` | Cross-tabulation | Multi-dimensional analysis |
+| `tableGetRange` | Extract data range | Bulk data retrieval |
+| `tableCreateFile` | Create new table | Output generation |
+| `tableAppendRows` | Append rows | Data combination |
+
+---
+
+## 4. BioMCP Tools Decision Tree
+
+### When to Use
+- Biomedical research queries
+- Literature search
+- Clinical trial data
+- Gene/variant/drug information
+- FDA regulatory data
+
+### Domain Selection
+
+```
+IF biomedical research query:
+  
+  Determine Domain:
+  
+  ├─ Literature/Papers
+  │  → biomcp_article_searcher(keywords, genes, diseases)
+  │  → biomcp_article_getter(pmid)
+  │  
+  ├─ Clinical Trials
+  │  → biomcp_trial_searcher(conditions, interventions)
+  │  → biomcp_trial_getter(nct_id)
+  │  → biomcp_trial_protocol_getter(nct_id)
+  │  → biomcp_trial_outcomes_getter(nct_id)
+  │  
+  ├─ Genes
+  │  → biomcp_gene_getter(gene_id_or_symbol)
+  │  
+  ├─ Variants/Mutations
+  │  → biomcp_variant_searcher(gene, significance)
+  │  → biomcp_variant_getter(variant_id)
+  │  
+  ├─ Drugs/Compounds
+  │  → biomcp_drug_getter(drug_id_or_name)
+  │  
+  ├─ FDA Data
+  │  → biomcp_openfda_adverse_searcher(drug, reaction)
+  │  → biomcp_openfda_label_searcher(name, indication)
+  │  → biomcp_openfda_approval_searcher(drug)
+  │  
+  └─ Cross-Domain Search
+     → biomcp_search(query="gene:BRAF AND disease:melanoma")
+```
+
+### Targeted Queries (BEST PRACTICE)
+
+```
+RULE: Use specific filters to narrow results upfront
+
+✅ DO:
+  biomcp_article_searcher(
+    genes=["BRAF", "NRAS"],
+    diseases=["melanoma"],
+    keywords=["treatment resistance"],
+    page_size=50
+  )
+
+❌ DON'T:
+  biomcp_search(query="BRAF")
+  → then manually filter through thousands of results
+```
+
+### Rate Limiting (MANDATORY)
+
+```
+ALWAYS use blockingTimer(0.3) between consecutive biomcp calls
+
+FOR each biomcp query:
+  result = biomcp_tool(...)
+  
+  IF more queries remain:
+    blockingTimer(0.3)  # 300ms delay
+  
+NEVER run concurrent biomcp calls (sequential only)
+```
+
+### Example: Literature Research Workflow
+
+```markdown
+User: "Find recent papers on BRAF V600E treatment resistance in melanoma"
+
+Agent actions:
+1. biomcp_article_searcher(
+     genes=["BRAF"],
+     diseases=["melanoma"],
+     variants=["V600E"],
+     keywords=["treatment resistance"],
+     page_size=20
+   )
+2. blockingTimer(0.3)
+3. FOR each relevant article:
+     biomcp_article_getter(pmid=article.id)
+     blockingTimer(0.3)
+4. Synthesize findings with citations
+```
+
+---
+
+## 5. Web Tools Decision Tree
+
+### When to Use
+- User provides specific URL
+- Need current information from web
+- Official biotech/pharma company data
+- Information not available in databases
+
+### Search vs Fetch
+
+```
+IF user provides specific URL:
+  → web-reader_webReader(url, return_format="markdown")
+  → Extract content
+
+IF user needs to find information:
+  → web-search-prime_web_search_prime(search_query)
+  → Identify relevant URLs
+  → web-reader_webReader(url) for promising results
+```
+
+### Source Quality Verification
+
+```
+Source Priority:
+  ✅ PREFER (High Quality):
+    - .gov domains (FDA, NIH, NCI)
+    - Official biotech/pharma company websites
+    - Peer-reviewed journal websites
+    - ClinicalTrials.gov
+  
+  ⚠️ CAUTION (Medium Quality):
+    - News websites (verify with primary sources)
+    - Industry publications
+    - Conference abstracts
+  
+  ❌ AVOID (Low Quality):
+    - Blogs and forums
+    - User-generated content
+    - Promotional materials
+    - Unverified claims
+```
+
+### Rate Limiting
+
+```
+FOR each web request:
+  result = webfetch(...)
+  
+  IF more requests remain:
+    blockingTimer(0.5)  # 500ms delay (more conservative)
+```
+
+---
+
+## 6. Parser Tools Decision Tree
+
+### When to Use
+- Need to parse structured file formats
+- Convert between formats
+- Process ontology files
+
+### Tool Selection
+
+```
+IF file is PubMed XML (.xml or .xml.gz):
+  → parse_pubmed_articleSet(
+      filePath,
+      outputMode="excel",  # or "single" or "individual"
+      outputFileName="pubmed_results.xlsx"
+    )
+
+IF file is OBO ontology (.obo):
+  → parse_obo_file(
+      filePath,
+      outputFileName="ontology.csv"
+    )
+
+IF file is JSON:
+  → jsonExtract(file_path)
+  → jsonValidate(data, schema) if needed
+```
+
+---
+
+## 7. Decision Flowchart Summary
+
+```
+START: User Query
+  │
+  ├─ Analyze user intent
+  │
+  ├─ Identify data source
+  │   ├─ Database → db* tools
+  │   ├─ Table file → table* tools
+  │   ├─ Web → web* tools
+  │   ├─ Biomedical → biomcp* tools
+  │   └─ Parse needed → parse* tools
+  │
+  ├─ Apply upfront filtering
+  │   └─ Use targeted queries/filters
+  │
+  ├─ Execute with rate limiting
+  │   └─ blockingTimer between API calls
+  │
+  ├─ Validate results
+  │   └─ Check data quality
+  │
+  └─ Synthesize with citations
+      └─ Reference-based report
+```
+
+---
+
+## Best Practices Summary
+
+### ✅ DO
+- Use targeted queries with specific filters
+- Apply upfront filtering at data source
+- Use named parameters in SQL queries
+- Implement rate limiting between API calls
+- Validate data before processing
+- Use decision trees to select tools
+
+### ❌ DON'T
+- Use bulk queries then filter in Python
+- Concatenate SQL strings
+- Run concurrent API calls
+- Skip rate limiting
+- Load entire datasets without filtering
+- Guess tool choices without analysis
+
+---
+
+## Common Patterns
+
+### Pattern 1: Database → Analysis
+```
+dbListTables() 
+→ dbDescribeTable() 
+→ dbQuery(with filters) 
+→ analysis
+```
+
+### Pattern 2: Literature Search
+```
+biomcp_article_searcher(filters) 
+→ blockingTimer(0.3) 
+→ biomcp_article_getter(pmid) 
+→ repeat
+```
+
+### Pattern 3: Table Analysis
+```
+tableGetSheetPreview() 
+→ determine row count 
+→ choose approach 
+→ execute
+```
+
+### Pattern 4: Web Research
+```
+web-search-prime() 
+→ identify URLs 
+→ web-reader_webReader() 
+→ extract data
+```

package/dist/skills/bioresearcher-core/patterns/citations.md

@@ -0,0 +1,234 @@
+# Citations Pattern
+
+Standardized citation format for biomedical research with automatic bibliography generation.
+
+## Overview
+
+Use this pattern to maintain consistent citations throughout research outputs. All findings must be backed by sources with proper citations.
+
+## Citation Style
+
+Use **numbered citations** for biomedical research:
+
+- In-text: [1], [2], [3]
+- Bibliography: Numbered list at end of document
+
+## In-Text Citation Format
+
+### Single Source
+```
+BRAF V600E mutations are found in approximately 50% of melanomas [1].
+```
+
+### Multiple Sources
+```
+Several studies have confirmed this association [1, 2, 3].
+```
+
+### Range of Sources
+```
+This has been extensively documented [1-5].
+```
+
+### Specific Claims
+```
+The drug was approved in 2011 [1] and has since become standard of care [2, 3].
+```
+
+## Bibliography Format
+
+### PubMed Articles
+
+```
+[1] Author1 AB, Author2 CD, Author3 EF. Article Title. Journal Name. Year;Volume(Issue):Pages. PMID: XXXXXXXX.
+```
+
+**Example:**
+```
+[1] Chapman PB, Hauschild A, Robert C, et al. Improved survival with vemurafenib in melanoma with BRAF V600E mutation. N Engl J Med. 2011;364(26):2507-2516. PMID: 21639808.
+```
+
+### Clinical Trials
+
+```
+[N] NCT ID: Trial Title. Phase X. Sponsor: Company/Institution. Status: Recruiting/Completed. URL: https://clinicaltrials.gov/ct2/show/NCTXXXXXXX
+```
+
+**Example:**
+```
+[2] NCT04280705: A Study of Encorafenib Plus Cetuximab With or Without Nivolumab in Metastatic Colorectal Cancer. Phase 2. Sponsor: Pfizer. Status: Completed. https://clinicaltrials.gov/ct2/show/NCT04280705
+```
+
+### Web Sources
+
+```
+[N] Page Title. Website Name. Published/Updated Date. URL. Accessed: YYYY-MM-DD.
+```
+
+**Example:**
+```
+[3] BRAF Gene. National Cancer Institute. Updated 2024. https://www.cancer.gov/about-cancer/causes-prevention/genetics/brca-genes. Accessed: 2024-01-15.
+```
+
+### Drug/Chemical Information
+
+```
+[N] Drug Name. DrugBank ID: DBXXXXX. ChEMBL ID: CHEMBLXXXXX. Indication: Disease.
+```
+
+**Example:**
+```
+[4] Vemurafenib. DrugBank ID: DB08881. ChEMBL ID: CHEMBL1229511. Indication: Melanoma.
+```
+
+### Gene Information
+
+```
+[N] Gene Symbol: Gene Name. Entrez ID: XXXXXX. HGNC ID: HGNC:XXXX.
+```
+
+**Example:**
+```
+[5] BRAF: B-Raf proto-oncogene, serine/threonine kinase. Entrez ID: 673. HGNC ID: HGNC:1097.
+```
+
+## Source-Specific Citation Workflows
+
+### From BioMCP Article Results
+
+When using `biomcp_search` or `biomcp_article_searcher`:
+
+```
+1. Extract from result:
+   - Authors (first author + "et al." if many)
+   - Title
+   - Journal
+   - Year
+   - PMID (from result.id or result.metadata)
+
+2. Use biomcp_article_getter(pmid="XXXXXXXX") for full metadata if needed
+
+3. Format citation
+```
+
+### From Clinical Trials
+
+When using `biomcp_trial_searcher` or `biomcp_trial_getter`:
+
+```
+1. Extract from result:
+   - NCT ID (result.id)
+   - Official title
+   - Phase
+   - Sponsor
+   - Status
+
+2. Format citation with ClinicalTrials.gov URL
+```
+
+### From Gene/Drug/Variant Information
+
+When using gene_getter, drug_getter, or variant_getter:
+
+```
+1. Extract identifiers:
+   - Gene: Symbol, Entrez ID, HGNC ID
+   - Drug: Name, DrugBank ID, ChEMBL ID
+   - Variant: HGVS notation, rsID, ClinVar significance
+
+2. Format as database citation
+```
+
+## Bibliography Section Format
+
+Place bibliography at the end of your document:
+
+```markdown
+## References
+
+[1] Chapman PB, Hauschild A, Robert C, et al. Improved survival with vemurafenib in melanoma with BRAF V600E mutation. N Engl J Med. 2011;364(26):2507-2516. PMID: 21639808.
+
+[2] NCT04280705: A Study of Encorafenib Plus Cetuximab With or Without Nivolumab in Metastatic Colorectal Cancer. Phase 2. Sponsor: Pfizer. Status: Completed. https://clinicaltrials.gov/ct2/show/NCT04280705
+
+[3] BRAF Gene. National Cancer Institute. Updated 2024. https://www.cancer.gov/about-cancer/causes-prevention/genetics/brca-genes. Accessed: 2024-01-15.
+```
+
+## Example: Research Report with Citations
+
+```markdown
+# BRAF Mutations in Melanoma
+
+## Overview
+
+BRAF V600E is the most common mutation in cutaneous melanoma, occurring in approximately 50% of cases [1]. This mutation leads to constitutive activation of the MAPK signaling pathway [2].
+
+## Treatment Landscape
+
+Targeted therapies against BRAF V600E have significantly improved outcomes:
+
+- **Vemurafenib**: First FDA-approved BRAF inhibitor (2011) [3]
+- **Dabrafenib**: Second-generation BRAF inhibitor [4]
+- **Combination therapy**: BRAF + MEK inhibition improves survival [5]
+
+## Clinical Trials
+
+Several ongoing trials are exploring combination approaches:
+
+- NCT04280705: Encorafenib + cetuximab ± nivolumab in colorectal cancer [6]
+- NCT04511078: Adjuvant dabrafenib + trametinib in melanoma [7]
+
+## References
+
+[1] Davies H, Bignell GR, Cox C, et al. Mutations of the BRAF gene in human cancer. Nature. 2002;417(6892):949-954. PMID: 12068308.
+
+[2] Wan PT, Garnett MJ, Roe SM, et al. Mechanism of activation of RAF-ERK signaling by oncogenic mutations of B-RAF. Cell. 2004;116(6):855-867. PMID: 15035987.
+
+[3] Chapman PB, Hauschild A, Robert C, et al. Improved survival with vemurafenib in melanoma with BRAF V600E mutation. N Engl J Med. 2011;364(26):2507-2516. PMID: 21639808.
+
+[4] Hauschild A, Grob JJ, Demidov LV, et al. Dabrafenib in BRAF-mutated metastatic melanoma: a multicentre, open-label, phase 3 randomised controlled trial. Lancet. 2012;380(9839):358-365. PMID: 22735384.
+
+[5] Robert C, Karaszewska B, Schachter J, et al. Improved overall survival in melanoma with combined dabrafenib and trametinib. N Engl J Med. 2015;372(1):30-39. PMID: 25399551.
+
+[6] NCT04280705: A Study of Encorafenib Plus Cetuximab With or Without Nivolumab in Metastatic Colorectal Cancer. Phase 2. Sponsor: Pfizer. Status: Completed. https://clinicaltrials.gov/ct2/show/NCT04280705
+
+[7] NCT04511078: Adjuvant Dabrafenib Plus Trametinib in Resected BRAF V600-Mutant Melanoma. Phase 3. Sponsor: Novartis. Status: Recruiting. https://clinicaltrials.gov/ct2/show/NCT04511078
+```
+
+## Citation Quality Standards
+
+### What to Cite
+
+| Source Type | Citation Required |
+|-------------|-------------------|
+| Published research | Yes |
+| Clinical trial data | Yes |
+| Drug approval info | Yes |
+| Gene/variant annotations | Yes |
+| Statistical claims | Yes |
+| Direct quotes | Yes |
+| General knowledge | No (e.g., "DNA has 4 bases") |
+
+### Citation Integrity
+
+1. **Verify source exists**: Always confirm PMID, NCT ID, URL is valid
+2. **Quote accurately**: Don't misrepresent findings
+3. **Cite primary sources**: Prefer original papers over reviews
+4. **Update outdated citations**: Use latest evidence when available
+
+## Tools for Citation Generation
+
+| Tool | Use Case |
+|------|----------|
+| `biomcp_article_getter` | Get full article metadata from PMID |
+| `biomcp_trial_getter` | Get trial details from NCT ID |
+| `biomcp_gene_getter` | Get gene identifiers |
+| `biomcp_drug_getter` | Get drug identifiers |
+
+## Best Practices
+
+1. **Cite as you write**: Add citations immediately when making claims
+2. **Number sequentially**: [1], [2], [3] in order of appearance
+3. **Include access dates**: For web sources, always include when accessed
+4. **Verify PMIDs**: Double-check PMID matches the article
+5. **Keep bibliography alphabetical by number**: Not by author
+6. **Format consistently**: Same style throughout document