medsci-skills 4.1.0

package/skills/find-cohort-gap/references/pattern_scoring_rubric.md

@@ -0,0 +1,169 @@
+# 6-Pattern Scoring Rubric
+
+## Overview
+
+Score each pattern 0 (absent) or 1 (present). Total: 0-6 points.
+Interpretation: 5-6 = top-tier, 3-4 = specialty journal, 1-2 = restructure or kill.
+
+---
+
+## P1: Longitudinal Advantage
+
+**Question:** Does the cohort's serial/repeated measurement structure create a clear
+edge over existing cross-sectional studies?
+
+**Score 1 if ALL of:**
+- The cohort has 3+ measurement timepoints for the key exposure variable
+- No prior study on this topic used serial/trajectory data
+- The research question benefits from temporal modeling (change over time, trajectory
+  clusters, time-to-event with time-varying exposure)
+
+**Score 0 if ANY of:**
+- The exposure is a one-time measurement (e.g., genetic variant, birth weight)
+- Prior longitudinal studies already exist for this topic
+- Serial data adds no interpretive value (e.g., stable demographic variable)
+
+**Examples:**
+- Score 1: Serial body composition → sarcopenia trajectory → mortality (no prior serial study)
+- Score 0: Blood type → cancer risk (blood type doesn't change over time)
+
+**Theoretical basis:** Repeated measures increase statistical efficiency by reducing
+within-subject variance and enabling trajectory-based phenotyping that cross-sectional
+designs cannot achieve (Lee et al., 2014, PMID 25464127).
+
+---
+
+## P2: Endpoint Upgrade
+
+**Question:** Can we escalate to a harder endpoint than existing studies?
+
+**Score 1 if BOTH of:**
+- The cohort links to mortality, cancer, or major cardiovascular event registries
+- Existing studies on this topic used only surrogate endpoints (biomarkers, imaging
+  findings, composite scores) without hard clinical outcomes
+
+**Score 0 if ANY of:**
+- The cohort lacks hard endpoint linkage
+- Prior studies already reported hard endpoints for this topic
+- The research question is inherently about a surrogate (e.g., mechanism study)
+
+**Examples:**
+- Score 1: Existing studies link fatty liver to liver enzymes only; our cohort links to
+  liver-related mortality and HCC incidence
+- Score 0: Existing studies already report all-cause mortality for this exposure
+
+**Endpoint hierarchy** (strongest to weakest):
+1. All-cause mortality
+2. Cause-specific mortality
+3. Major adverse events (MACE, cancer diagnosis)
+4. Hospitalization
+5. Disease incidence (physician diagnosis)
+6. Surrogate markers (lab values, imaging scores)
+
+---
+
+## P3: Cohort Uniqueness
+
+**Question:** Is the cohort's population, scale, or setting distinctive?
+
+**Score 1 if ANY of:**
+- Largest cohort for this topic (>5x larger than existing studies)
+- First study in this ethnic/geographic population
+- Screening-based population (no referral bias) when prior studies used hospital cohorts
+- Unique data linkage not available elsewhere (e.g., national registry + health checkup)
+- Community-dwelling general population when prior studies used disease-specific cohorts
+
+**Score 0 if:**
+- Similar-sized cohorts with the same population type have published on this topic
+
+**Examples:**
+- Score 1: 486K health checkup participants vs existing studies of 3-9K referral patients
+- Score 0: Another 500K cohort from the same country already published on this topic
+
+---
+
+## P4: PI-Topic Alignment
+
+**Question:** Does the PI's expertise and reputation strengthen this topic?
+
+**Score 1 if ANY of:**
+- PI holds a society leadership role directly relevant to the topic
+- PI has 5+ first/corresponding author papers in this specific domain
+- PI is an editorial board member of a target journal in this field
+
+**Score 0 if:**
+- PI's expertise is only tangentially related
+- No specific PI identified (skip this pattern; score out of 5 instead)
+
+**Why this matters:** A PI with society standing in the topic area signals that the
+study has expert oversight. Editors recognize this. The PI's name also guides target
+journal selection (e.g., hepatology society president -> J Hepatol).
+
+**When no PI is specified:** Remove this pattern from scoring. Interpret:
+4-5/5 = top-tier, 2-3/5 = specialty, 0-1/5 = restructure.
+
+---
+
+## P5: Comparison Table Gaps (3+)
+
+**Question:** Does the THIS STUDY column show 3+ unique features vs all existing papers?
+
+**Score 1 if:**
+- The comparison table has at least 3 rows where THIS STUDY has a checkmark/advantage
+  that NO prior paper has
+
+**Score 0 if:**
+- Fewer than 3 unique differentiators
+
+**Common differentiator categories:**
+1. Study design (longitudinal vs cross-sectional)
+2. Sample size (order of magnitude larger)
+3. Serial measurements (multiple timepoints vs single)
+4. Hard endpoints (mortality vs surrogate)
+5. Population type (screening vs referral)
+6. Ethnicity/geography (first in this population)
+7. Subgroup analyses (age/sex/comorbidity stratification)
+8. Adjustment for key confounders (missing in prior studies)
+9. Exposure definition (validated operational definition vs ICD-only)
+10. Follow-up duration (significantly longer)
+
+**Construction method:**
+1. Identify 3-5 most relevant existing papers from saturation scan
+2. Create table with Feature rows and Paper columns + THIS STUDY column
+3. For each feature, check whether each paper and THIS STUDY address it
+4. Count features unique to THIS STUDY
+
+---
+
+## P6: Complementary Design
+
+**Question:** Can this topic pair with another study from the same cohort?
+
+**Score 1 if ANY of:**
+- A complementary analysis using the same DB but different population subset is
+  feasible (e.g., diabetic vs non-diabetic; viral vs non-viral liver disease)
+- The same exposure can be studied against a different outcome in a companion paper
+- The topic creates a "series" with a previously published paper from the same cohort
+
+**Score 0 if:**
+- The topic is standalone with no natural complement
+- The complementary analysis would be trivially similar (not publishable separately)
+
+**Why this matters:** Paired papers from the same cohort strengthen both: the second
+paper can reference the first as "in this cohort, we previously showed..." and reviewers
+see a programmatic research line, not a one-off analysis.
+
+---
+
+## Quick Reference Card
+
+```
+Pattern         | Key Signal
+----------------|------------------------------------------
+P1 Longitudinal | "No prior study used serial data for this"
+P2 Endpoint     | "We add mortality/cancer to surrogate-only literature"
+P3 Uniqueness   | "Largest / first in this population / no referral bias"
+P4 PI Alignment | "PI is society president in this exact field"
+P5 Comparison   | "3+ checkmarks unique to THIS STUDY"
+P6 Complement   | "Natural pair study exists in same DB"
+```

package/skills/find-cohort-gap/references/saturation_query_templates.md

@@ -0,0 +1,143 @@
+# Literature Saturation Query Templates
+
+## Purpose
+
+These templates help construct PubMed queries for the Phase 3 saturation scan.
+Adapt the bracketed terms to the specific topic.
+
+---
+
+## Basic Saturation Query
+
+```
+([exposure MeSH] OR [exposure free text]) AND ([outcome MeSH] OR [outcome free text])
+AND (cohort OR longitudinal OR prospective OR "follow-up")
+```
+
+**Filters:** English, Humans, last 20 years (to capture the full landscape)
+
+## Longitudinal-Specific Query
+
+To check if anyone has used serial/repeated measurements for this topic:
+
+```
+([exposure] OR [exposure synonym]) AND ([outcome] OR [outcome synonym])
+AND ("repeated measure*" OR "serial" OR "trajectory" OR "longitudinal change"
+OR "time-varying" OR "growth curve" OR "latent class trajectory")
+```
+
+## Meta-Analysis Check Query
+
+To verify if a meta-analysis already exists:
+
+```
+([exposure] OR [exposure synonym]) AND ([outcome] OR [outcome synonym])
+AND ("meta-analysis"[Publication Type] OR "systematic review"[Publication Type])
+```
+
+If a meta-analysis exists → Red grade (avoid unless doing NMA).
+
+## Population-Specific Queries
+
+### Korean/Asian population filter
+```
+AND (Korea* OR Korean OR "Republic of Korea" OR Asia* OR Japan* OR China OR Chinese
+OR Taiwan*)
+```
+
+### Health checkup / screening population filter
+```
+AND ("health checkup" OR "health screening" OR "health examination" OR "medical checkup"
+OR "periodic health exam*" OR "annual exam*")
+```
+
+### Large cohort filter (to find comparator studies)
+```
+AND ("national health insurance" OR "claims data" OR "administrative data"
+OR "population-based" OR "nationwide" OR "registry")
+```
+
+---
+
+## Saturation Grading Protocol
+
+After running the basic saturation query:
+
+### Step 1: Count total results
+- 0-2: Blue Ocean
+- 3-10: Possible Green Field (proceed to Step 2)
+- 10-30: Possible Yellow (proceed to Step 2)
+- 30+: Likely Red (check for MA in Step 3)
+
+### Step 2: Check longitudinal gap
+Run the longitudinal-specific query.
+- 0 results with serial/trajectory data → upgrade one grade
+- 1-2 results → maintain current grade
+- 3+ results → no upgrade
+
+### Step 3: Check meta-analysis existence
+Run the MA check query.
+- MA exists and is comprehensive → Red (firm)
+- MA exists but outdated (>5 years) or limited scope → Yellow (update MA possible)
+- No MA → maintain current grade
+
+### Step 4: Final grade assignment
+
+| Base Count | Longitudinal Papers | MA Exists? | Final Grade |
+|------------|-------------------|------------|-------------|
+| 0-2 | 0 | No | Blue Ocean |
+| 3-10 | 0 | No | **Green Field** |
+| 3-10 | 1-2 | No | Yellow |
+| 10-30 | 0 | No | Green Field (upgraded) |
+| 10-30 | 1-2 | No | Yellow |
+| 10-30 | 3+ | No | Yellow |
+| 30+ | Any | No | Yellow (borderline Red) |
+| Any | Any | Yes (recent) | Red |
+| Any | Any | Yes (outdated) | Yellow |
+
+---
+
+## Example: Fatty Liver and Cardiovascular Mortality
+
+### Basic query
+```
+("fatty liver" OR "hepatic steatosis" OR NAFLD OR MASLD) AND
+("cardiovascular mortality" OR "cardiac death" OR "MACE")
+AND (cohort OR longitudinal OR prospective)
+```
+Result: ~45 papers → base grade Red
+
+### Longitudinal check
+```
+("fatty liver" OR "hepatic steatosis") AND ("cardiovascular mortality")
+AND ("trajectory" OR "serial" OR "repeated measure*" OR "longitudinal change")
+```
+Result: 2 papers → no upgrade
+
+### MA check
+```
+("fatty liver" OR NAFLD) AND ("cardiovascular mortality")
+AND ("meta-analysis"[PT] OR "systematic review"[PT])
+```
+Result: 3 MAs → confirmed Red
+
+**Conclusion:** Avoid this topic unless using truly unique data angle.
+
+---
+
+## Tips for Effective Saturation Scanning
+
+1. **Start broad, then narrow.** If the broad query returns >30, add population or
+   design filters to find the exact niche.
+
+2. **Check the "last 3 years" subset.** A topic with 20 total papers but 15 in the
+   last 3 years is trending (good for timeliness, bad for novelty).
+
+3. **Read the most recent review article.** It maps the field faster than scanning
+   individual papers. Look for "future research directions" sections.
+
+4. **Check for registered protocols.** Search PROSPERO or ClinicalTrials.gov for
+   ongoing studies that haven't published yet — these are invisible competitors.
+
+5. **Use Semantic Scholar** for citation network analysis. A paper with 200+ citations
+   on this exact topic means the field is well-established.

package/skills/find-cohort-gap/skill.yml

@@ -0,0 +1,35 @@
+schema_version: 2
+name: find-cohort-gap
+layer: D
+owner_domain: research_gap_analysis
+
+when_to_use: "Find research gaps in a longitudinal cohort DB by profiling its strengths, matching PI expertise, and scanning literature saturation."
+when_NOT_to_use: "Finding meta-analysis topics (use ma-scout); designing a chosen study (use design-study)."
+
+inputs:
+  - "cohort profile / data dictionary"
+  - "PI expertise"
+  - "literature landscape"
+outputs:
+  - "ranked topic proposals with gap evidence"
+side_effects:
+  - writes_report_artifacts
+  - network_access_literature
+downstream_consumers:
+  - design-study
+  - define-variables
+forbidden_actions:
+  - claim_a_gap_without_literature_evidence
+  - fabricate_saturation_counts
+
+# v2.1 quality card
+purpose: "Rank under-studied topics for a specific cohort, each backed by literature-saturation evidence and feasibility."
+safety_boundaries:
+  - "Each proposed gap cites the literature scan that supports it; saturation counts come from real searches."
+  - "Advisory report only; does not design or execute studies."
+known_limitations:
+  - "Literature scans are point-in-time; a gap can close between scan and submission."
+  - "No standalone demo; proposals require domain judgement."
+validation_commands:
+  - "re-run the saturation search before committing to a topic"
+evidence_surface: manual_workflow

package/skills/find-journal/POLICY.md

@@ -0,0 +1,87 @@
+# Journal Profile Policy
+
+This document defines what a profile must satisfy to live in the public profile library
+(`skills/find-journal/references/journal_profiles/` and the matching `write-paper`
+directory) versus the user-local private library (`$HOME/.claude/private-journal-profiles/`).
+
+## Why two tiers
+
+The public library ships with the skill and is consumed by every user. A profile that
+misrepresents a journal's author guidelines — wrong ISSN, wrong article types, wrong AI
+policy wording — propagates that error to every downstream researcher. The private tier
+exists so a single user can keep working notes and personal-use profiles without polluting
+the shared library.
+
+## The verification bar (public library)
+
+Every public profile must meet **all** of the following. No exceptions, no defaults.
+
+### Source discipline
+
+1. The journal's homepage was opened directly (not inferred from a sibling journal).
+2. The journal's Author Guidelines page was opened directly, or equivalent authoritative
+   sections were pasted into the session by the maintainer.
+3. Every line of the profile cites or is traceable to content on (1) or (2). Plausible
+   inference from adjacent journals is not acceptable, even when the journals are in the
+   same publisher family.
+
+### Field-level checks
+
+- `Publisher` — transcribed from the journal's own masthead / about page.
+- `ISSN (print/online)` — transcribed from the journal's own masthead or ISSN Portal
+  (portal.issn.org) entry for that exact journal.
+- `Homepage` and `Author guidelines` URLs — both return 200 OK when the profile is
+  written. If the guidelines page is 403/login-gated, either paste the accessible
+  sections or defer to the private tier.
+- `Article Types Accepted` — listed in the journal's own submission/instructions page.
+  No "typical for this publisher family" article types.
+- `AI policy` sentence — transcribed from the journal's or publisher's AI policy page.
+  Family-level defaults (e.g., "follows AHA policy aligned with ICMJE") are only
+  acceptable if the journal's own page links to or repeats that family policy; they are
+  not a substitute for checking.
+- `Special Notes` — any "Choose X over Y" decision rule must be defensible from what the
+  two journals' own scope statements say, not from general reputation.
+
+### Proof of verification
+
+Profile authors or maintainers should keep a brief evidence note — either a 1-line
+comment at the bottom of the profile, a PR description, or a commit message — stating
+which pages were opened and on what date. This lets future audits check whether a profile
+has drifted.
+
+## Single entry point for profile creation
+
+Profiles are added and edited through the `/add-journal` skill. Ad-hoc profile creation
+(spawning a research agent, writing freehand, copying from another profile) is not
+permitted for the public library because it bypasses the skill's built-in 403 handling,
+TODO-marking, and anti-hallucination rules.
+
+For one-off personal profiles a user is welcome to write freehand into the private tier,
+but the same source-discipline principles apply — infer less, verify more.
+
+## Promotion checklist (private → public)
+
+Before moving a profile from your local private profiles directory (outside this
+repo) into `skills/*/references/journal_profiles/`, confirm each item:
+
+- [ ] Journal homepage fetched successfully today and opened manually.
+- [ ] Author guidelines page fetched successfully today and opened manually.
+- [ ] ISSN cross-checked against portal.issn.org entry for the exact journal name.
+- [ ] Publisher name transcribed from the journal's masthead, not inferred.
+- [ ] Article types list present on the journal's own page — no family inference.
+- [ ] AI policy sentence transcribed from the journal's or publisher's policy page — no
+      sibling-journal copy-paste.
+- [ ] "Choose X over Y" decision rule defensible from each journal's own scope text.
+- [ ] No `[TODO: verify at journal site]` markers remaining.
+- [ ] Commit message records which pages were opened and on what date.
+
+Only after all items pass does `git mv` from private to public become appropriate.
+
+## Demotion (public → private)
+
+If an existing public profile is found to fail this bar, either:
+
+1. Fix it in place and commit the correction with evidence, or
+2. Demote it back to the private tier with `git mv` and a commit message recording why.
+
+Silently leaving a questionable profile in the public library is not an option.