Find Cohort Gap

Find-Cohort-Gap Skill

Output directory: user-specified (default: current working directory).

Phase 0: Cohort Intake

The cohort does not have to be one this skill has heard of. Route on what the user actually has.

Input adapter (local codebook / documents)

python3 "${CLAUDE_SKILL_DIR}/scripts/build_cohort_profile.py" \
  --codebook data_dictionary.csv \
  --context narrative_review.pdf --context https://example.org/guideline \
  --cohort-name "Institutional CT registry" --out-dir .

Formats: .csv / .tsv / .json / .md / .txt (stdlib), .xlsx (needs openpyxl), .pdf (needs pdftotext). A .csv is auto-detected as a codebook (rows are variables) or a data export (the header row is the variable list). Writes cohort_profile.md + cohort_profile.json (+ context_extract.md).

Do not read the codebook yourself and summarise it. A paraphrased, merged, or invented variable poisons every downstream claim — the intersection matrix, the feasibility gate, and eventually the manuscript's Methods. The adapter enumerates variables verbatim with provenance (file:row). Read cohort_profile.md; do not re-derive it.

The adapter infers, and shows its work for, the variable cluster map, serial / repeated-measure groups (evidence for P1 Longitudinal Advantage), and endpoint candidates (evidence for P2 Endpoint Upgrade). A variable matching no cluster keyword is left unclassified — review those, since the lexicon is not exhaustive.

What the adapter cannot know — ASK, never guess

A codebook does not state any of the following; each is emitted as [UNKNOWN - ask the user]:

1. Sample size (N at baseline, N with follow-up)
2. Time span (enrollment period, follow-up duration, measurement intervals)
3. Known limitations (healthy volunteer bias, attrition, missing-data patterns)
4. Existing publications from this cohort (to avoid duplicating them)
5. IRB status and data-access route

Collect these from the user before Phase 2, because a guessed N flows into the Phase 5 feasibility gate and makes it pass or fail for a reason unrelated to the cohort. Also confirm the setting (institution type, country, population type) and any special strengths the variable names cannot reveal — registry linkage, biobank availability, a distinctive population.

Gate: Present the cohort profile summary, including the [UNKNOWN] list and the unclassified variables. Confirm before proceeding.

Phase 1: PI/CA Profiling

Profile the intended PI or corresponding author to find topic-expertise alignment. If no PI is specified, skip this phase and use variable clusters alone in Phase 2.

1. Search PubMed for the PI's recent publications (last 5 years) with /search-lit's E-utilities script: bash "${CLAUDE_SKILL_DIR}/../search-lit/references/pubmed_eutils.sh" search "AuthorLastName AuthorFirstInitial[Author]" 30 Extract top keyword clusters from titles/abstracts.
2. Identify specialty signals: academic society positions (president, board member, editor), subspecialty focus areas, preferred journal tiers.
3. Build a PI keyword map: 5-10 keyword clusters ranked by publication frequency.

Output: PI profile card (name, affiliation, top keywords, society roles, preferred journals).

Phase 2: Intersection Matrix

Cross cohort variable clusters with PI expertise to generate candidate topics.

Method

Create a matrix: rows = DB variable clusters, columns = PI keyword clusters. Score each cell 0-3:

• 3: PI has published in this exact intersection (direct match)
• 2: PI's subspecialty covers this area (strong relevance)
• 1: Tangential connection (possible but needs framing)
• 0: No connection

Candidate Generation

1. Extract all cells scoring 2-3 as primary candidates.
2. For cells scoring 1, apply the A-B substitution test: "Has someone published [this analysis] with [a different exposure/outcome] in a similar cohort?" If yes, substituting the PI's specialty variable creates a viable candidate.
3. Generate 20-40 candidate topic statements in PICO format — P population from the cohort, E exposure/predictor variable(s), C comparison group, O outcome (preferably hard endpoint).

Discipline Alignment Filter

Before saturation scanning, identify the intended first author's department/specialty. The primary exposure variable must belong to that discipline (e.g., radiology first author → imaging variable as the primary exposure). Kill candidates where the primary exposure is outside the first author's discipline — a strong PI match alone is insufficient if the first author cannot claim ownership of the core variable.

Gate: Present the intersection matrix and top 20 candidates (post-discipline filter). User selects 8-12 for saturation scanning.

Phase 3: Literature Saturation Scan

For each selected candidate, determine how saturated the literature is.

Search Strategy

For each candidate:

1. Build a PubMed query: (exposure terms) AND (outcome terms) AND (cohort OR longitudinal OR prospective)
2. Execute search via /search-lit E-utilities.
3. Count total results, then ask the Critical Filter question — "Has anyone published this with serial/repeated measurements?" — and check whether a meta-analysis exists. Grade: