@yeyuan98/opencode-bioresearcher-plugin 1.5.2 → 1.5.3

package/dist/skills/bioresearcher-core/patterns/bioresearcher/report-template.md

@@ -1,613 +1,613 @@
-# Reference-Based Report Template
-
-Standardized template for professional research reports with complete data provenance and citations.
-
-## Overview
-
-This pattern defines the mandatory structure for all bioresearcher agent reports, ensuring:
-- Complete data provenance documentation
-- Clear analysis methodology
-- Proper citations and bibliography
-- Reproducible research
-
----
-
-## Complete Report Template
-
-```markdown
-# [Research Topic Title]
-
-**Generated by:** BioResearcher AI Agent  
-**Date:** [YYYY-MM-DD]  
-**Research Scope:** [Brief description of research question in 1-2 sentences]
-
----
-
-## Executive Summary
-
-[2-3 sentence overview of key findings with most critical citations [1, 2]]
-
-**Key Findings:**
-- [Finding 1 with citation [1]]
-- [Finding 2 with citation [2]]
-- [Finding 3 with citation [3]]
-
----
-
-## 1. Data Sources
-
-### 1.1 Primary Data Origin
-
-**Source Type:** [Database / Literature / Clinical Trials / Web / Local Files / Mixed]
-
-**Source Details:**
-
-| Source | Type | Location/Query | Date Accessed |
-|--------|------|----------------|---------------|
-| [Source 1] | [Database/Literature/Web] | [File path, URL, or query] | [YYYY-MM-DD] |
-| [Source 2] | [Database/Literature/Web] | [File path, URL, or query] | [YYYY-MM-DD] |
-
-**Data Scope:**
-- **Records Retrieved:** [Number]
-- **Date Range:** [Start date - End date, if applicable]
-- **Filters Applied:** [List filters used]
-- **Sample Size:** [Final dataset size after filtering]
-
-### 1.2 Data Access Method
-
-**Tools Used:**
-- [Tool 1: e.g., dbQuery]
-- [Tool 2: e.g., biomcp_article_searcher]
-- [Tool 3: e.g., tableFilterRows]
-
-**Queries/Filters Applied:**
-
-```sql
--- Database query example
-SELECT * FROM clinical_trials 
-WHERE phase = 'Phase 3' 
-  AND status = 'Recruiting'
-  AND condition LIKE '%melanoma%'
-```
-
-```python
-# BioMCP query example
-biomcp_article_searcher(
-  genes=["BRAF"],
-  diseases=["melanoma"],
-  keywords=["treatment resistance"],
-  page_size=50
-)
-```
-
-```typescript
-// Table filter example
-tableFilterRows(
-  file_path="data/trials.xlsx",
-  column="Phase",
-  operator="=",
-  value="Phase 3"
-)
-```
-
-### 1.3 Data Quality Notes
-
-**Completeness:**
-- [Any missing data or gaps]
-- [Fields with null values: %]
-
-**Limitations:**
-- [Limitation 1: e.g., "Data only includes trials registered after 2020"]
-- [Limitation 2: e.g., "Non-English publications excluded"]
-
-**Quality Assessment:**
-- [How data quality was verified]
-- [Any validation steps taken]
-
----
-
-## 2. Analysis Methodology
-
-### 2.1 Analysis Approach
-
-**Selected Approach:** [Table Tools / long-table-summary Skill / Custom Python / Hybrid]
-
-**Decision Rationale:**
-- [Why this approach was chosen over alternatives]
-- [Example: "Selected long-table-summary skill due to dataset size (150 rows) and need for structured classification output"]
-
-### 2.2 Tools & Skills Used
-
-**Skills Loaded:**
-- [Skill 1: e.g., bioresearcher-core]
-- [Skill 2: e.g., long-table-summary]
-
-**Tools Applied:**
-1. [Tool 1 with purpose]
-2. [Tool 2 with purpose]
-3. [Tool 3 with purpose]
-
-**Python Scripts:**
-- [Script path 1: e.g., .scripts/py/trial_analysis.py]
-- [Script path 2: e.g., .scripts/py/statistical_tests.py]
-
-### 2.3 Analysis Steps
-
-**Step 1: [Step Name]**
-- Tool/Skill: [Tool or skill used]
-- Action: [What was done]
-- Result: [Outcome]
-
-**Step 2: [Step Name]**
-- Tool/Skill: [Tool or skill used]
-- Action: [What was done]
-- Result: [Outcome]
-
-**Step 3: [Step Name]**
-- Tool/Skill: [Tool or skill used]
-- Action: [What was done]
-- Result: [Outcome]
-
-[Continue for all steps]
-
-### 2.4 Validation & Quality Control
-
-**Validation Method:**
-- [Method: e.g., jsonValidate with schema, manual review, cross-referencing]
-- [Sample size validated: X of Y records]
-
-**Error Handling:**
-- [Retry logic applied: Yes/No]
-- [Failed operations: Number and reasons]
-- [Fallback approaches: Description]
-
-**Data Verification:**
-- [How results were verified for accuracy]
-- [Cross-validation with other sources: Yes/No, details]
-
----
-
-## 3. Findings
-
-### 3.1 [Finding Category 1]
-
-[Detailed description of findings with inline citations [1, 2, 3]]
-
-**Key Data Points:**
-
-| Metric | Value | Confidence | Source |
-|--------|-------|------------|--------|
-| [Metric 1] | [Value] | [High/Medium/Low] | [Citation] |
-| [Metric 2] | [Value] | [High/Medium/Low] | [Citation] |
-| [Metric 3] | [Value] | [High/Medium/Low] | [Citation] |
-
-**Supporting Evidence:**
-- [Evidence 1 with citation [4]]
-- [Evidence 2 with citation [5]]
-
-**Visual Representation:**
-[If applicable, include or reference charts/tables]
-
-### 3.2 [Finding Category 2]
-
-[Detailed description with inline citations [6, 7]]
-
-**Comparison Table:**
-
-| Category | Group A | Group B | Difference | P-value | Source |
-|----------|---------|---------|------------|---------|--------|
-| [Metric] | [Value] | [Value] | [+/- X%] | [0.XX] | [Citation] |
-
-**Trends Observed:**
-- [Trend 1 with citation [8]]
-- [Trend 2 with citation [9]]
-
-### 3.3 [Finding Category 3]
-
-[Continue structure for additional findings]
-
----
-
-## 4. Limitations & Considerations
-
-### 4.1 Data Limitations
-
-**Coverage Gaps:**
-- [Gap 1: e.g., "Limited to English-language publications"]
-- [Gap 2: e.g., "Database only includes trials from US/Europe"]
-
-**Temporal Limitations:**
-- [Date range limitations]
-- [Outdated information concerns]
-
-**Quality Limitations:**
-- [Data quality issues]
-- [Potential biases]
-
-### 4.2 Methodological Limitations
-
-**Analysis Constraints:**
-- [Constraint 1: e.g., "Sample size too small for statistical significance"]
-- [Constraint 2: e.g., "Unable to control for confounding variables"]
-
-**Tool Limitations:**
-- [Tool limitation 1]
-- [Tool limitation 2]
-
-### 4.3 Generalizability
-
-**Applicability:**
-- [Where findings can be applied]
-- [Where findings may not apply]
-
-**Extrapolation Risks:**
-- [Risks of over-generalizing results]
-
----
-
-## 5. Recommendations
-
-### 5.1 Primary Recommendations
-
-**Recommendation 1: [Title]**
-- **Action:** [Specific action recommended]
-- **Rationale:** [Why this action is recommended]
-- **Supporting Evidence:** [Citation [10]]
-- **Priority:** [High/Medium/Low]
-
-**Recommendation 2: [Title]**
-- **Action:** [Specific action recommended]
-- **Rationale:** [Why this action is recommended]
-- **Supporting Evidence:** [Citation [11]]
-- **Priority:** [High/Medium/Low]
-
-### 5.2 Future Research Directions
-
-- [Direction 1 with rationale]
-- [Direction 2 with rationale]
-
----
-
-## References
-
-### Published Research
-
-[1] Author1 AB, Author2 CD, Author3 EF, et al. Article Title. Journal Name. Year;Volume(Issue):Pages. PMID: XXXXXXXX.
-
-[2] Author4 GH, Author5 IJ. Another Article Title. Another Journal. Year;Volume(Issue):Pages. DOI: 10.XXXX/XXXXX.
-
-### Clinical Trials
-
-[3] 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
-
-[4] Page Title. Website Name. Published/Updated: YYYY-MM-DD. URL. Accessed: YYYY-MM-DD.
-
-### Databases
-
-[5] Database Name. Version X.Y. Organization. Query: [SQL or search criteria]. Accessed: YYYY-MM-DD.
-
-### Drug/Gene/Variant Information
-
-[6] BRAF: B-Raf proto-oncogene, serine/threonine kinase. Entrez ID: 673. HGNC ID: HGNC:1097. https://www.ncbi.nlm.nih.gov/gene/673
-
-[7] Vemurafenib. DrugBank ID: DB08881. ChEMBL ID: CHEMBL1229511. https://go.drugbank.com/drugs/DB08881
-
----
-
-## Appendix
-
-### A. Raw Data
-
-**Data Availability:**
-- [Location of raw data files]
-- [Data format: Excel, CSV, JSON]
-- [File sizes]
-
-**Access Instructions:**
-[How to access the raw data]
-
-### B. Analysis Code
-
-**Python Scripts:**
-- [Script 1: .scripts/py/[name].py]
-- [Script 2: .scripts/py/[name].py]
-
-**Configuration Files:**
-- [Config file paths, if any]
-
-### C. Reproducibility Notes
-
-**Environment:**
-- Python version: [X.Y.Z]
-- Key dependencies: [pandas X.Y.Z, numpy X.Y.Z]
-- Package manager: uv
-
-**Reproduction Steps:**
-1. [Step 1]
-2. [Step 2]
-3. [Step 3]
-
-**Expected Output:**
-[Description of expected results if analysis is reproduced]
-
----
-
-**Report prepared by:** BioResearcher AI Agent  
-**Research completed:** [YYYY-MM-DD HH:MM]  
-**Report generated:** [YYYY-MM-DD HH:MM]  
-**Total sources cited:** [N]
-```
-
----
-
-## Data Provenance Requirements
-
-### Rule 1: Every Claim Must Have Provenance
-
-**Three options (at least one required):**
-
-1. **Citation** - Reference to bibliography [N]
-2. **Data Source** - Explicit mention of where data came from
-3. **Analysis Method** - How the conclusion was derived
-
-### Example: Proper vs. Improper Provenance
-
-#### ❌ BAD: No Provenance
-```markdown
-BRAF V600E is found in 50% of melanomas.
-```
-
-#### ⚠️ ADEQUATE: Citation Only
-```markdown
-BRAF V600E is found in approximately 50% of melanomas [1].
-```
-
-#### ✅ GOOD: Complete Provenance
-```markdown
-BRAF V600E mutations are found in approximately 50% of cutaneous melanomas 
-[1], based on analysis of 2,847 patient samples from the TCGA database 
-(query performed 2024-01-15, filter: primary melanoma, stage II-IV). 
-
-This finding is consistent with previous reports showing 40-60% prevalence 
-in this population [2, 3].
-```
-
----
-
-## Citation Standards
-
-### In-Text Citation Format
-
-**Single Source:**
-```markdown
-BRAF V600E mutations are found in approximately 50% of melanomas [1].
-```
-
-**Multiple Sources:**
-```markdown
-Several studies have confirmed this association [1, 2, 3].
-```
-
-**Range of Sources:**
-```markdown
-This has been extensively documented [1-5].
-```
-
-**Specific Claims:**
-```markdown
-The drug was approved in 2011 [1] and has since become standard of care [2, 3].
-```
-
-### Bibliography Format by Source Type
-
-#### Published Research
-```
-[N] Author1 AB, Author2 CD, Author3 EF, et al. 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
-```
-
-**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.
-```
-
-#### Databases
-```
-[N] Database Name. Version X.Y. Organization. Query: [SQL or search criteria]. Accessed: YYYY-MM-DD.
-```
-
-**Example:**
-```
-[4] ClinicalTrials.gov Database. U.S. National Library of Medicine. Query: "melanoma AND Phase 3 AND Recruiting". Accessed: 2024-01-15.
-```
-
-#### Drug/Gene/Variant Information
-```
-[N] Gene Symbol: Gene Name. Entrez ID: XXXXXX. HGNC ID: HGNC:XXXX. URL
-```
-
-**Example:**
-```
-[5] BRAF: B-Raf proto-oncogene, serine/threonine kinase. Entrez ID: 673. HGNC ID: HGNC:1097. https://www.ncbi.nlm.nih.gov/gene/673
-```
-
----
-
-## Report Quality Checklist
-
-Before finalizing report, verify:
-
-### Data Sources Section
-- [ ] All data sources listed with types
-- [ ] Access dates provided for all sources
-- [ ] Queries/filters documented
-- [ ] Data scope clearly defined
-- [ ] Quality limitations noted
-
-### Analysis Methodology Section
-- [ ] Analysis approach explained
-- [ ] Decision rationale provided
-- [ ] All tools/skills listed
-- [ ] Step-by-step process documented
-- [ ] Validation methods described
-
-### Findings Section
-- [ ] All claims have citations
-- [ ] Data provenance provided
-- [ ] Confidence levels stated
-- [ ] Supporting evidence included
-- [ ] Tables/figures referenced
-
-### Limitations Section
-- [ ] Data gaps acknowledged
-- [ ] Methodological constraints noted
-- [ ] Generalizability discussed
-
-### References Section
-- [ ] All in-text citations in bibliography
-- [ ] Format consistent by source type
-- [ ] URLs/PMIDs/DOIs included
-- [ ] Access dates for web sources
-- [ ] Alphabetically numbered (not by author)
-
-### Appendix Section
-- [ ] Raw data location provided
-- [ ] Analysis code referenced
-- [ ] Reproducibility notes included
-
----
-
-## Template Usage Examples
-
-### Example 1: Literature Review Report
-
-```markdown
-# BRAF V600E Mutation Prevalence in Melanoma
-
-**Generated by:** BioResearcher AI Agent  
-**Date:** 2024-01-15  
-**Research Scope:** Systematic review of BRAF V600E mutation prevalence 
-in cutaneous melanoma across published studies
-
----
-
-## Executive Summary
-
-BRAF V600E mutations occur in approximately 50% of cutaneous melanomas 
-[1, 2], with prevalence varying by geographic region and melanoma subtype 
-[3]. This review analyzed 15 studies encompassing 8,247 patients.
-
-**Key Findings:**
-- Overall prevalence: 48-52% in cutaneous melanoma [1, 2, 3]
-- Higher in chronic sun-damaged skin: 56% [4]
-- Lower in acral melanoma: 15-20% [5]
-
-[Continue with full template sections...]
-```
-
-### Example 2: Clinical Trial Analysis Report
-
-```markdown
-# Phase 3 Melanoma Trials Analysis
-
-**Generated by:** BioResearcher AI Agent  
-**Date:** 2024-01-15  
-**Research Scope:** Analysis of recruiting Phase 3 clinical trials for 
-melanoma treatments
-
----
-
-## 1. Data Sources
-
-### 1.1 Primary Data Origin
-
-**Source Type:** Database (ClinicalTrials.gov)
-
-**Source Details:**
-
-| Source | Type | Location/Query | Date Accessed |
-|--------|------|----------------|---------------|
-| ClinicalTrials.gov | Database | API + web scraping | 2024-01-15 |
-
-**Data Scope:**
-- **Records Retrieved:** 127 trials
-- **Date Range:** 2000-2024
-- **Filters Applied:** Phase 3, Melanoma, Recruiting
-- **Sample Size:** 127 trials
-
-[Continue with full template sections...]
-```
-
----
-
-## Common Mistakes to Avoid
-
-### Mistake 1: Missing Data Provenance
-```
-❌ BAD: "Response rates were 65%"
-✅ GOOD: "Response rates were 65% [1] based on analysis of 42 Phase 3 
-          trials from ClinicalTrials.gov (accessed 2024-01-15, filter: 
-          melanoma AND recruiting)"
-```
-
-### Mistake 2: Incomplete Methodology
-```
-❌ BAD: "We analyzed the data"
-✅ GOOD: "Analysis was performed using tableGroupBy tool to aggregate 
-          trials by phase, followed by custom Python statistical analysis 
-          (.scripts/py/trial_statistics.py) to compare response rates"
-```
-
-### Mistake 3: Inconsistent Citations
-```
-❌ BAD: Mixed citation styles, missing PMIDs
-✅ GOOD: Consistent format by source type, all identifiers included
-```
-
-### Mistake 4: No Limitations Section
-```
-❌ BAD: Presenting findings as absolute truth
-✅ GOOD: Acknowledging data gaps, methodological constraints, and 
-          generalizability limits
-```
-
----
-
-## Report Review Process
-
-### Self-Review Checklist
-
-1. **Provenance Check:** Every claim has source citation or data origin
-2. **Citation Check:** All [N] references exist in bibliography
-3. **Format Check:** Bibliography follows source-type templates
-4. **Completeness Check:** All template sections present
-5. **Clarity Check:** Technical terms explained
-6. **Accuracy Check:** Numbers and statistics verified
-
-### Quality Standards
-
-- **Transparency:** All methods and data sources documented
-- **Reproducibility:** Another researcher could reproduce results
-- **Credibility:** High-quality sources, proper citations
-- **Professionalism:** Academic writing standards, clear structure
+# Reference-Based Report Template
+
+Standardized template for professional research reports with complete data provenance and citations.
+
+## Overview
+
+This pattern defines the mandatory structure for all bioresearcher agent reports, ensuring:
+- Complete data provenance documentation
+- Clear analysis methodology
+- Proper citations and bibliography
+- Reproducible research
+
+---
+
+## Complete Report Template
+
+```markdown
+# [Research Topic Title]
+
+**Generated by:** BioResearcher AI Agent  
+**Date:** [YYYY-MM-DD]  
+**Research Scope:** [Brief description of research question in 1-2 sentences]
+
+---
+
+## Executive Summary
+
+[2-3 sentence overview of key findings with most critical citations [1, 2]]
+
+**Key Findings:**
+- [Finding 1 with citation [1]]
+- [Finding 2 with citation [2]]
+- [Finding 3 with citation [3]]
+
+---
+
+## 1. Data Sources
+
+### 1.1 Primary Data Origin
+
+**Source Type:** [Database / Literature / Clinical Trials / Web / Local Files / Mixed]
+
+**Source Details:**
+
+| Source | Type | Location/Query | Date Accessed |
+|--------|------|----------------|---------------|
+| [Source 1] | [Database/Literature/Web] | [File path, URL, or query] | [YYYY-MM-DD] |
+| [Source 2] | [Database/Literature/Web] | [File path, URL, or query] | [YYYY-MM-DD] |
+
+**Data Scope:**
+- **Records Retrieved:** [Number]
+- **Date Range:** [Start date - End date, if applicable]
+- **Filters Applied:** [List filters used]
+- **Sample Size:** [Final dataset size after filtering]
+
+### 1.2 Data Access Method
+
+**Tools Used:**
+- [Tool 1: e.g., dbQuery]
+- [Tool 2: e.g., biomcp_article_searcher]
+- [Tool 3: e.g., tableFilterRows]
+
+**Queries/Filters Applied:**
+
+```sql
+-- Database query example
+SELECT * FROM clinical_trials 
+WHERE phase = 'Phase 3' 
+  AND status = 'Recruiting'
+  AND condition LIKE '%melanoma%'
+```
+
+```python
+# BioMCP query example
+biomcp_article_searcher(
+  genes=["BRAF"],
+  diseases=["melanoma"],
+  keywords=["treatment resistance"],
+  page_size=50
+)
+```
+
+```typescript
+// Table filter example
+tableFilterRows(
+  file_path="data/trials.xlsx",
+  column="Phase",
+  operator="=",
+  value="Phase 3"
+)
+```
+
+### 1.3 Data Quality Notes
+
+**Completeness:**
+- [Any missing data or gaps]
+- [Fields with null values: %]
+
+**Limitations:**
+- [Limitation 1: e.g., "Data only includes trials registered after 2020"]
+- [Limitation 2: e.g., "Non-English publications excluded"]
+
+**Quality Assessment:**
+- [How data quality was verified]
+- [Any validation steps taken]
+
+---
+
+## 2. Analysis Methodology
+
+### 2.1 Analysis Approach
+
+**Selected Approach:** [Table Tools / long-table-summary Skill / Custom Python / Hybrid]
+
+**Decision Rationale:**
+- [Why this approach was chosen over alternatives]
+- [Example: "Selected long-table-summary skill due to dataset size (150 rows) and need for structured classification output"]
+
+### 2.2 Tools & Skills Used
+
+**Skills Loaded:**
+- [Skill 1: e.g., bioresearcher-core]
+- [Skill 2: e.g., long-table-summary]
+
+**Tools Applied:**
+1. [Tool 1 with purpose]
+2. [Tool 2 with purpose]
+3. [Tool 3 with purpose]
+
+**Python Scripts:**
+- [Script path 1: e.g., .scripts/py/trial_analysis.py]
+- [Script path 2: e.g., .scripts/py/statistical_tests.py]
+
+### 2.3 Analysis Steps
+
+**Step 1: [Step Name]**
+- Tool/Skill: [Tool or skill used]
+- Action: [What was done]
+- Result: [Outcome]
+
+**Step 2: [Step Name]**
+- Tool/Skill: [Tool or skill used]
+- Action: [What was done]
+- Result: [Outcome]
+
+**Step 3: [Step Name]**
+- Tool/Skill: [Tool or skill used]
+- Action: [What was done]
+- Result: [Outcome]
+
+[Continue for all steps]
+
+### 2.4 Validation & Quality Control
+
+**Validation Method:**
+- [Method: e.g., jsonValidate with schema, manual review, cross-referencing]
+- [Sample size validated: X of Y records]
+
+**Error Handling:**
+- [Retry logic applied: Yes/No]
+- [Failed operations: Number and reasons]
+- [Fallback approaches: Description]
+
+**Data Verification:**
+- [How results were verified for accuracy]
+- [Cross-validation with other sources: Yes/No, details]
+
+---
+
+## 3. Findings
+
+### 3.1 [Finding Category 1]
+
+[Detailed description of findings with inline citations [1, 2, 3]]
+
+**Key Data Points:**
+
+| Metric | Value | Confidence | Source |
+|--------|-------|------------|--------|
+| [Metric 1] | [Value] | [High/Medium/Low] | [Citation] |
+| [Metric 2] | [Value] | [High/Medium/Low] | [Citation] |
+| [Metric 3] | [Value] | [High/Medium/Low] | [Citation] |
+
+**Supporting Evidence:**
+- [Evidence 1 with citation [4]]
+- [Evidence 2 with citation [5]]
+
+**Visual Representation:**
+[If applicable, include or reference charts/tables]
+
+### 3.2 [Finding Category 2]
+
+[Detailed description with inline citations [6, 7]]
+
+**Comparison Table:**
+
+| Category | Group A | Group B | Difference | P-value | Source |
+|----------|---------|---------|------------|---------|--------|
+| [Metric] | [Value] | [Value] | [+/- X%] | [0.XX] | [Citation] |
+
+**Trends Observed:**
+- [Trend 1 with citation [8]]
+- [Trend 2 with citation [9]]
+
+### 3.3 [Finding Category 3]
+
+[Continue structure for additional findings]
+
+---
+
+## 4. Limitations & Considerations
+
+### 4.1 Data Limitations
+
+**Coverage Gaps:**
+- [Gap 1: e.g., "Limited to English-language publications"]
+- [Gap 2: e.g., "Database only includes trials from US/Europe"]
+
+**Temporal Limitations:**
+- [Date range limitations]
+- [Outdated information concerns]
+
+**Quality Limitations:**
+- [Data quality issues]
+- [Potential biases]
+
+### 4.2 Methodological Limitations
+
+**Analysis Constraints:**
+- [Constraint 1: e.g., "Sample size too small for statistical significance"]
+- [Constraint 2: e.g., "Unable to control for confounding variables"]
+
+**Tool Limitations:**
+- [Tool limitation 1]
+- [Tool limitation 2]
+
+### 4.3 Generalizability
+
+**Applicability:**
+- [Where findings can be applied]
+- [Where findings may not apply]
+
+**Extrapolation Risks:**
+- [Risks of over-generalizing results]
+
+---
+
+## 5. Recommendations
+
+### 5.1 Primary Recommendations
+
+**Recommendation 1: [Title]**
+- **Action:** [Specific action recommended]
+- **Rationale:** [Why this action is recommended]
+- **Supporting Evidence:** [Citation [10]]
+- **Priority:** [High/Medium/Low]
+
+**Recommendation 2: [Title]**
+- **Action:** [Specific action recommended]
+- **Rationale:** [Why this action is recommended]
+- **Supporting Evidence:** [Citation [11]]
+- **Priority:** [High/Medium/Low]
+
+### 5.2 Future Research Directions
+
+- [Direction 1 with rationale]
+- [Direction 2 with rationale]
+
+---
+
+## References
+
+### Published Research
+
+[1] Author1 AB, Author2 CD, Author3 EF, et al. Article Title. Journal Name. Year;Volume(Issue):Pages. PMID: XXXXXXXX.
+
+[2] Author4 GH, Author5 IJ. Another Article Title. Another Journal. Year;Volume(Issue):Pages. DOI: 10.XXXX/XXXXX.
+
+### Clinical Trials
+
+[3] 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
+
+[4] Page Title. Website Name. Published/Updated: YYYY-MM-DD. URL. Accessed: YYYY-MM-DD.
+
+### Databases
+
+[5] Database Name. Version X.Y. Organization. Query: [SQL or search criteria]. Accessed: YYYY-MM-DD.
+
+### Drug/Gene/Variant Information
+
+[6] BRAF: B-Raf proto-oncogene, serine/threonine kinase. Entrez ID: 673. HGNC ID: HGNC:1097. https://www.ncbi.nlm.nih.gov/gene/673
+
+[7] Vemurafenib. DrugBank ID: DB08881. ChEMBL ID: CHEMBL1229511. https://go.drugbank.com/drugs/DB08881
+
+---
+
+## Appendix
+
+### A. Raw Data
+
+**Data Availability:**
+- [Location of raw data files]
+- [Data format: Excel, CSV, JSON]
+- [File sizes]
+
+**Access Instructions:**
+[How to access the raw data]
+
+### B. Analysis Code
+
+**Python Scripts:**
+- [Script 1: .scripts/py/[name].py]
+- [Script 2: .scripts/py/[name].py]
+
+**Configuration Files:**
+- [Config file paths, if any]
+
+### C. Reproducibility Notes
+
+**Environment:**
+- Python version: [X.Y.Z]
+- Key dependencies: [pandas X.Y.Z, numpy X.Y.Z]
+- Package manager: uv
+
+**Reproduction Steps:**
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+**Expected Output:**
+[Description of expected results if analysis is reproduced]
+
+---
+
+**Report prepared by:** BioResearcher AI Agent  
+**Research completed:** [YYYY-MM-DD HH:MM]  
+**Report generated:** [YYYY-MM-DD HH:MM]  
+**Total sources cited:** [N]
+```
+
+---
+
+## Data Provenance Requirements
+
+### Rule 1: Every Claim Must Have Provenance
+
+**Three options (at least one required):**
+
+1. **Citation** - Reference to bibliography [N]
+2. **Data Source** - Explicit mention of where data came from
+3. **Analysis Method** - How the conclusion was derived
+
+### Example: Proper vs. Improper Provenance
+
+#### ❌ BAD: No Provenance
+```markdown
+BRAF V600E is found in 50% of melanomas.
+```
+
+#### ⚠️ ADEQUATE: Citation Only
+```markdown
+BRAF V600E is found in approximately 50% of melanomas [1].
+```
+
+#### ✅ GOOD: Complete Provenance
+```markdown
+BRAF V600E mutations are found in approximately 50% of cutaneous melanomas 
+[1], based on analysis of 2,847 patient samples from the TCGA database 
+(query performed 2024-01-15, filter: primary melanoma, stage II-IV). 
+
+This finding is consistent with previous reports showing 40-60% prevalence 
+in this population [2, 3].
+```
+
+---
+
+## Citation Standards
+
+### In-Text Citation Format
+
+**Single Source:**
+```markdown
+BRAF V600E mutations are found in approximately 50% of melanomas [1].
+```
+
+**Multiple Sources:**
+```markdown
+Several studies have confirmed this association [1, 2, 3].
+```
+
+**Range of Sources:**
+```markdown
+This has been extensively documented [1-5].
+```
+
+**Specific Claims:**
+```markdown
+The drug was approved in 2011 [1] and has since become standard of care [2, 3].
+```
+
+### Bibliography Format by Source Type
+
+#### Published Research
+```
+[N] Author1 AB, Author2 CD, Author3 EF, et al. 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
+```
+
+**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.
+```
+
+#### Databases
+```
+[N] Database Name. Version X.Y. Organization. Query: [SQL or search criteria]. Accessed: YYYY-MM-DD.
+```
+
+**Example:**
+```
+[4] ClinicalTrials.gov Database. U.S. National Library of Medicine. Query: "melanoma AND Phase 3 AND Recruiting". Accessed: 2024-01-15.
+```
+
+#### Drug/Gene/Variant Information
+```
+[N] Gene Symbol: Gene Name. Entrez ID: XXXXXX. HGNC ID: HGNC:XXXX. URL
+```
+
+**Example:**
+```
+[5] BRAF: B-Raf proto-oncogene, serine/threonine kinase. Entrez ID: 673. HGNC ID: HGNC:1097. https://www.ncbi.nlm.nih.gov/gene/673
+```
+
+---
+
+## Report Quality Checklist
+
+Before finalizing report, verify:
+
+### Data Sources Section
+- [ ] All data sources listed with types
+- [ ] Access dates provided for all sources
+- [ ] Queries/filters documented
+- [ ] Data scope clearly defined
+- [ ] Quality limitations noted
+
+### Analysis Methodology Section
+- [ ] Analysis approach explained
+- [ ] Decision rationale provided
+- [ ] All tools/skills listed
+- [ ] Step-by-step process documented
+- [ ] Validation methods described
+
+### Findings Section
+- [ ] All claims have citations
+- [ ] Data provenance provided
+- [ ] Confidence levels stated
+- [ ] Supporting evidence included
+- [ ] Tables/figures referenced
+
+### Limitations Section
+- [ ] Data gaps acknowledged
+- [ ] Methodological constraints noted
+- [ ] Generalizability discussed
+
+### References Section
+- [ ] All in-text citations in bibliography
+- [ ] Format consistent by source type
+- [ ] URLs/PMIDs/DOIs included
+- [ ] Access dates for web sources
+- [ ] Alphabetically numbered (not by author)
+
+### Appendix Section
+- [ ] Raw data location provided
+- [ ] Analysis code referenced
+- [ ] Reproducibility notes included
+
+---
+
+## Template Usage Examples
+
+### Example 1: Literature Review Report
+
+```markdown
+# BRAF V600E Mutation Prevalence in Melanoma
+
+**Generated by:** BioResearcher AI Agent  
+**Date:** 2024-01-15  
+**Research Scope:** Systematic review of BRAF V600E mutation prevalence 
+in cutaneous melanoma across published studies
+
+---
+
+## Executive Summary
+
+BRAF V600E mutations occur in approximately 50% of cutaneous melanomas 
+[1, 2], with prevalence varying by geographic region and melanoma subtype 
+[3]. This review analyzed 15 studies encompassing 8,247 patients.
+
+**Key Findings:**
+- Overall prevalence: 48-52% in cutaneous melanoma [1, 2, 3]
+- Higher in chronic sun-damaged skin: 56% [4]
+- Lower in acral melanoma: 15-20% [5]
+
+[Continue with full template sections...]
+```
+
+### Example 2: Clinical Trial Analysis Report
+
+```markdown
+# Phase 3 Melanoma Trials Analysis
+
+**Generated by:** BioResearcher AI Agent  
+**Date:** 2024-01-15  
+**Research Scope:** Analysis of recruiting Phase 3 clinical trials for 
+melanoma treatments
+
+---
+
+## 1. Data Sources
+
+### 1.1 Primary Data Origin
+
+**Source Type:** Database (ClinicalTrials.gov)
+
+**Source Details:**
+
+| Source | Type | Location/Query | Date Accessed |
+|--------|------|----------------|---------------|
+| ClinicalTrials.gov | Database | API + web scraping | 2024-01-15 |
+
+**Data Scope:**
+- **Records Retrieved:** 127 trials
+- **Date Range:** 2000-2024
+- **Filters Applied:** Phase 3, Melanoma, Recruiting
+- **Sample Size:** 127 trials
+
+[Continue with full template sections...]
+```
+
+---
+
+## Common Mistakes to Avoid
+
+### Mistake 1: Missing Data Provenance
+```
+❌ BAD: "Response rates were 65%"
+✅ GOOD: "Response rates were 65% [1] based on analysis of 42 Phase 3 
+          trials from ClinicalTrials.gov (accessed 2024-01-15, filter: 
+          melanoma AND recruiting)"
+```
+
+### Mistake 2: Incomplete Methodology
+```
+❌ BAD: "We analyzed the data"
+✅ GOOD: "Analysis was performed using tableGroupBy tool to aggregate 
+          trials by phase, followed by custom Python statistical analysis 
+          (.scripts/py/trial_statistics.py) to compare response rates"
+```
+
+### Mistake 3: Inconsistent Citations
+```
+❌ BAD: Mixed citation styles, missing PMIDs
+✅ GOOD: Consistent format by source type, all identifiers included
+```
+
+### Mistake 4: No Limitations Section
+```
+❌ BAD: Presenting findings as absolute truth
+✅ GOOD: Acknowledging data gaps, methodological constraints, and 
+          generalizability limits
+```
+
+---
+
+## Report Review Process
+
+### Self-Review Checklist
+
+1. **Provenance Check:** Every claim has source citation or data origin
+2. **Citation Check:** All [N] references exist in bibliography
+3. **Format Check:** Bibliography follows source-type templates
+4. **Completeness Check:** All template sections present
+5. **Clarity Check:** Technical terms explained
+6. **Accuracy Check:** Numbers and statistics verified
+
+### Quality Standards
+
+- **Transparency:** All methods and data sources documented
+- **Reproducibility:** Another researcher could reproduce results
+- **Credibility:** High-quality sources, proper citations
+- **Professionalism:** Academic writing standards, clear structure