ma-scout

# MA Scout Skill

You are helping a medical researcher discover meta-analysis topics.
Two modes are available depending on the starting point.

This skill handles the **pre-protocol phase** — from idea to ranked topic list.
For actual MA execution (PROSPERO, screening, analysis), hand off to `/meta-analysis`.

## Mode Selection

Determine the mode from user input:

| Signal | Mode |
|--------|------|
| Professor name or profile URL provided | **A: Professor-first** |
| Clinical question, keyword, trend, or "find me a topic" | **B: Topic-first** |
| Both supplied (e.g., "this topic with this professor") | **A** (topic as filter) |

If ambiguous, ask the user whether to search by professor (supervisor-first) or by
topic (question-first).

## Communication Rules

- Communicate with the user in their preferred language (typically Korean).
- Research questions, PICO/PIRD, and README content in English.
- Medical terminology always in English.

---

## Inputs

### Mode A: Professor-first
- Professor name (native-language + English)
- Profile URL (ScholarWorks, SKKU Faculty, Google Scholar, ORCID)
- PubMed author link (preferably with cauthor_id for disambiguation)
- Known specialty (e.g., "thoracic imaging", "abdominal imaging")
- Affiliation history (e.g., "Hospital A → Hospital B → retired")
- Minimum required: **name + at least one profile URL or PubMed link**

### Mode B: Topic-first
- Clinical question or keyword (e.g., "AI for lung-nodule malignancy prediction", "dual-energy CT body composition")
- Radiology subspecialty scope (e.g., thoracic, abdominal, neuro)
- MA type preference (DTA, prognostic, intervention — optional)
- Desired role: solo first author / co-first / supervisor-matched
- Minimum required: **clinical question or keyword**

---

## Workflow

> **Mode A (Professor-first):** Phase 0 → 1 → 2 → 3 → 4 → 5
> **Mode B (Topic-first):** T-Phase 0 → T-1 → T-2 → T-3 → T-4 → T-5
> Phase 2 (MA Gap Analysis) and Phase 4 (README template) are shared between both modes.

---

# ═══════════════════════════════════════════
# MODE A: PROFESSOR-FIRST WORKFLOW
# ═══════════════════════════════════════════

### Phase 0: Disambiguation & Context Confirmation

**Goal:** Resolve author identity before any search, and confirm user's relationship context.

**CRITICAL — Do this BEFORE any PubMed search:**

1. **Resolve full English name first:**
   - If cauthor_id is provided → fetch that specific PMID page to get full name + affiliation
   - NEVER start with initials-only search (e.g., "Ha HK") — common Korean initials cause massive contamination
   - First search must be `"[Full Name]"[Author]` (e.g., `"Ha Hyun Kwon"[Author]`)

2. **Confirm affiliation chain with user:**
   - Ask the user whether `{detected affiliation}` matches the professor's history,
     and request the user's relationship to the professor so topic proposals can be
     tuned accordingly.
   - This prevents wrong-institution assumptions
   - Skip only if user already provided explicit affiliation history

3. **Profile URL fallback chain** (Scopus requires auth, so plan alternatives):
   - 1st: PubMed full name search (always works)
   - 2nd: Google Scholar profile (WebSearch `"[Full Name]" radiology scholar`)
   - 3rd: ResearchGate profile (WebSearch `"[Full Name]" researchgate radiology`)
   - 4th: ScholarWorks / SKKU / university faculty page (if URL provided)
   - Last: Scopus/ScienceDirect (often fails due to auth — do NOT rely on it)

---

### Phase 1: Profile Exploration (E-utilities API)

**Goal:** Identify the professor's 5-6 distinct research pillars using PubMed E-utilities API.

**CRITICAL — Use E-utilities API, NOT WebFetch for PubMed:**
- Scripts: `~/.claude/skills/search-lit/references/pubmed_eutils.sh` + `parse_pubmed.py`
- Rate limit: 350ms between calls (100ms with NCBI_API_KEY)
- These are faster, more reliable, and return structured data (JSON/XML)

**Step 1 — Total publication count + PMID list:**
```bash
bash ~/.claude/skills/search-lit/references/pubmed_eutils.sh search \
  '"[Full Name]"[Author]' 200 \
  | python3 ~/.claude/skills/search-lit/references/parse_pubmed.py esearch
```

**Step 2 — Fetch metadata for MeSH-based clustering (parallel):**
```bash
# Get PMIDs from Step 1, then fetch summaries
bash ~/.claude/skills/search-lit/references/pubmed_eutils.sh fetch_json \
  "PMID1,PMID2,..." \
  | python3 ~/.claude/skills/search-lit/references/parse_pubmed.py esummary
```

**Step 3 — Topic-specific counts (launch 4-5 searches in parallel via Bash):**
```bash
# Run these in parallel Bash calls
bash ~/.claude/skills/search-lit/references/pubmed_eutils.sh search \
  '"[Full Name]"[Author] AND "keyword1"' 5
bash ~/.claude/skills/search-lit/references/pubmed_eutils.sh search \
  '"[Full Name]"[Author] AND "keyword2"' 5
# ... repeat for each suspected pillar keyword
```

**Step 4 — MeSH term extraction for automatic pillar clustering:**
```bash
# Fetch full XML for top-cited papers to extract MeSH headings
bash ~/.claude/skills/search-lit/references/pubmed_eutils.sh fetch \
  "PMID1,PMID2,...,PMID20" \
  | python3 -c "
import sys, xml.etree.ElementTree as ET
from collections import Counter
root = ET.fromstring(sys.stdin.read())
mesh_counts = Counter()
for article in root.findall('.//PubmedArticle'):
    for mh in article.findall('.//MeshHeading/DescriptorName'):
        mesh_counts[mh.text] += 1
for term, count in mesh_counts.most_common(30):
    print(f'{count:3d}  {term}')
"
```
→ Top MeSH terms reveal natural research pillars (e.g., "Colonography, Computed Tomographic" = CTC pillar).

**Step 5 — Google Scholar profile (parallel with PubMed calls):**
- WebSearch: `"[Full Name]" radiology scholar google` for h-index, citation data

**Output: Pillar Summary Table**

| Pillar | Domain | Representative keywords | MeSH terms | Est. # papers |
|--------|--------|-------------------------|-----------|---------------|
| 1 | ... | ... | ... | ~N+ |

---

### Phase 2: MA Gap Analysis (Multi-Source)

**Goal:** For ea