@research-copilot/plugin 1.1.16 → 1.1.18

package/dist/skills/medical-imaging-review/SKILL.md

@@ -0,0 +1,295 @@
+---
+name: medical-imaging-review
+description: Write peer-review-quality comprehensive reviews for medical imaging AI research (segmentation, detection, classification across CT, MRI, X-ray, ultrasound, pathology). Use this skill whenever the user wants to produce a survey paper, systematic review, literature analysis, or "综述" on deep learning for medical imaging; whenever they mention writing a "review paper" / "literature review" / "系统综述" / "narrative review" / "scoping review" in a medical-AI context; whenever they want a draft suitable for journal submission rather than internal notes; whenever they need help organizing a multi-section method survey with vendor / regulatory / clinical translation coverage. This skill enforces fact-checking, citation integrity, and flagship-review writing voice — NOT a fill-in-the-blank template that invites hallucination. Use it especially when the goal is a publishable manuscript and not just a draft to discuss.
+metadata:
+  author: louwill
+  version: 3.0.0
+  prior_version_lessons: "v2.0.0 produced drafts that needed extensive multi-day fact-check revision (coronary-cta-paper case): 17 placeholder DOIs, 30-40 [N] drift errors, fabricated method modules, vendor-style citations, 10-subsection flat method taxonomy, AI-tone hedging throughout. v3.0.0 directly addresses these failure modes."
+---
+
+# Medical Imaging AI Literature Review Skill (v3.0.0)
+
+Produce comprehensive reviews that pass first-round peer review on factual grounds, not just structural grounds.
+
+This is **not** a template-filling skill. It is a write-with-verify discipline.
+
+---
+
+## Quick Start
+
+A review project lives in 4 files (3 you write, 1 the skill provides):
+
+```
+project_root/
+├── PARADIGM.md            # Style spec from 2-3 exemplar reviews (Phase 0)
+├── CLAUDE.md              # Project-specific terminology + literature inventory
+├── IMPLEMENTATION_PLAN.md # 3-axis outline + per-claim verification checklist
+└── manuscript_draft.md    # The actual manuscript
+```
+
+Follow the 6-phase workflow in [references/WORKFLOW.md](references/WORKFLOW.md). The phases are: paradigm capture → init → collect-and-verify → 3-axis outline → write-with-per-claim-verification → multi-agent peer review.
+
+---
+
+## Core Principles
+
+### Writing voice — match strength to evidence, not hedge by default
+
+Calibrate language to evidence strength, not to a fixed hedging register.
+
+When ≥2 independent peer-reviewed groups confirm a finding, state it strongly. When evidence is single-source or contested, state it cautiously. When evidence is absent, say so.
+
+**Avoid the LLM tells:**
+- "has shown promising results"
+- "may suggest"
+- "interestingly,"
+- "it is worth noting that"
+- "in recent years,"
+- "demonstrates the effectiveness of"
+- "may offer significant advantages"
+
+These phrases are AI-detector top features. Real flagship-review authors don't use them. Strip them.
+
+**Take a position when evidence supports it.** Neutral catalogue is the LLM default and the failure mode to avoid. See [Verdict sentences](#verdict-sentences) below.
+
+### Citations — every claim verified before commit
+
+Every `[N]` citation must satisfy four checks:
+
+1. The cited paper **exists** (DOI / PMID resolves on PubMed or Crossref).
+2. The **author list** matches the first-source (especially first and last author).
+3. The **numeric claim** in the body sentence (Dice, HR, sample size, etc.) appears in the cited paper's abstract or results section.
+4. The **directional claim** in the body sentence (higher/lower, increased/decreased) matches the source's stated direction.
+
+If any check fails, the citation is broken — fix before continuing. See [references/CITATION_INTEGRITY.md](references/CITATION_INTEGRITY.md) for the full protocol.
+
+### Method descriptions — read first, write after
+
+Do **not** fill in a template like `[Author] et al. [ref] proposed [method]... Achieves Dice of X.XX`. That template is a hallucination trap.
+
+Use this discipline instead:
+
+1. **Read** the actual paper (abstract + methods + results). For arXiv, use `read_paper`. For closed-access, use Zotero MCP to access the user's library.
+2. **Note** the actual module names, the actual benchmark, the actual numbers, in your own working notes — not in the manuscript yet.
+3. **Write** the method description from those notes, citing specific numbers and module names verbatim from the paper.
+4. **Verify** by spot-checking 1-2 of the numbers against the paper one more time before moving on.
+
+If you can't access the paper, do not write about its internal architecture or specific performance numbers. Cite it for the contribution-level claim only ("first to apply X to Y") and move on.
+
+### Heading depth — Nature Reviews uses two levels
+
+- **H2** (`##`) for top-level sections (Introduction, Methods, Applications, Discussion, ...).
+- **H3** (`###`) for subsections.
+- **H4** (`####`) is forbidden in body. Use bold lead-in `**Topic.**` paragraph starters for deeper grouping.
+- **Number prefixes** (`1.`, `1.1`, `1.2.3`) are forbidden in section titles. Nature Reviews / Nat Med / Lancet / JACC don't use them in narrative reviews.
+
+### Equations — in a Box, not in body
+
+Display equations (DSC, IoU, clDice, FedAvg, GCN propagation, ...) appear in **Boxes**, not inline in body paragraphs. Textbook formulas can be referenced ("the Dice similarity coefficient — see Box 1") but should not be displayed inline.
+
+If a formula has no methodological insight worth displaying (e.g., FedAvg averaging), describe it in prose instead of showing it.
+
+### Vendor names — only in the regulatory/products table
+
+Vendor names (HeartFlow, Cleerly, Caristo, Keya, Shukun, ...) appear ONLY in the Commercial Products / Regulatory & Validation table. In body text use category descriptors:
+
+- ✗ "HeartFlow's CT-FFR product was validated in NXT, ADVANCE, and PACIFIC..."
+- ✓ "The first FDA-cleared CT-FFR product (Table N, row 1) was validated in NXT, ADVANCE, and PACIFIC..."
+
+Reason: scatter-cited vendor names look like marketing copy and undermine the review's authority.
+
+---
+
+## Standard Review Structure
+
+```markdown
+# [Title]: <evocative subtitle>
+
+## Key Points
+- 4-5 bullets, each 1-3 sentences, expressing the main conclusions.
+
+## Abstract
+
+## Introduction
+### Clinical background
+### Technical challenge
+### Scope and contributions
+
+## Datasets and evaluation metrics
+(Table 1: public datasets)
+(Box 1: evaluation metrics with equations)
+
+## Methods                              # 3-axis grouping, NOT flat 10-subsection list
+### Architectural priors
+**CNN-based design.** ... (bold lead-in for sub-grouping)
+**Transformer-based design.** ...
+**Mamba and state-space design.** ...
+
+### Inductive priors
+**Topology-aware design.** ...
+**Multi-task design.** ...
+**Graph-based design.** ...
+
+### Data regime
+**Self-supervised pre-training.** ...
+**Foundation models.** ...
+**Federated learning.** ...
+**Physics-informed models.** ...
+
+(Table 2: representative methods with modality / family / dataset / metric)
+
+## Downstream applications
+### [Application 1]
+### [Application 2]
+### [Application 3]
+
+## Translation to clinical practice
+(Table 3: commercial products with regulatory + validation)
+
+## Outstanding challenges
+
+## Future directions
+
+## References
+```
+
+Notes:
+- No number prefixes on headings.
+- §Methods is 3 H3 subsections (the three axes), with bold lead-ins for each method family inside.
+- Tables 1, 2, 3 are typically enough. Box 1 (metrics) is typical. Avoid 5+ tables.
+- Verdict sentences cluster at the end of §Methods axis subsections and at the end of clinical translation discussions — not after every paragraph.
+
+---
+
+## Verdict Sentences
+
+Each H3 method-axis subsection (Architectural priors / Inductive priors / Data regime) should close with **one verdict sentence** expressing authorial position. Choose the 3-5 most opinionated positions across the whole manuscript — don't put verdicts on every paragraph.
+
+Verdict templates:
+- "[Family] is currently the most cost-effective design choice for [problem]."
+- "[Family] has yet to demonstrate clear advantage over [alternative] in clinical-grade evaluations."
+- "[Family] is best understood as complementary to [alternative], not a replacement."
+- "The next [N] years will determine whether [family] becomes the default backbone or remains a research curiosity."
+
+Neutral catalogue is the LLM default and exactly what flagship review editors push back on. Force yourself to take 3-5 positions.
+
+---
+
+## Required Elements
+
+- **Key Points box** (4-5 bullets, 1-3 sentences each) after the title.
+- **Tables 1-3**: datasets, methods, commercial products.
+- **Box 1**: evaluation metrics with formulas.
+- **Figures**: typically 3-5 (overview/taxonomy, representative architectures, workflow, performance landscape).
+- **References**: cite only what supports the argument. Quantity is downstream of substance — don't pad to a target count.
+- **Verdict sentences**: 3-5 across the whole manuscript, clustered at axis-section ends.
+
+---
+
+## Heading Depth
+
+See [Core Principles ▸ Heading depth](#heading-depth--nature-reviews-uses-two-levels) above. Hard rules:
+
+- Max 2 heading levels in body.
+- No number prefixes.
+- Use bold lead-in `**Topic.**` for deeper subsubsections.
+
+---
+
+## Equations
+
+See [Core Principles ▸ Equations](#equations--in-a-box-not-in-body) above. All display equations go in Box 1 (or rare additional Boxes for specific protocols). Textbook formulas with no methodological insight should be described in prose, not displayed.
+
+---
+
+## Vendor Names
+
+See [Core Principles ▸ Vendor names](#vendor-names--only-in-the-regulatoryproducts-table) above. Vendor names live in Table 3 only; body text uses category descriptors with table cross-reference.
+
+---
+
+## Citation Style
+
+```markdown
+# Data citation
+"...achieved Dice of 0.730 on ImageCAS [N]"
+
+# Method citation
+"Xu et al. [N] introduced..."
+
+# Multi-citation (max 4 in one bracket — beyond that, regroup the claim)
+"Multiple groups demonstrated this effect [N1, N2, N3]"
+
+# Comparative
+"While [N1] focused on architecture, [N2] addressed the data side"
+```
+
+`[N]` in body must match the bibliography entry [N], and bibliography [N] must be the paper the body sentence is actually attributing the claim to. See [references/CITATION_INTEGRITY.md](references/CITATION_INTEGRITY.md) Rule 3.
+
+---
+
+## Literature Sources
+
+Use all three in combination:
+
+| Source | Best for | Tools |
+|---|---|---|
+| **ArXiv** | Methodological preprints, ML/AI advances | `mcp__arxiv-mcp-server__search_papers`, `read_paper` |
+| **PubMed** | Peer-reviewed clinical / validation studies | `mcp__pubmed-mcp-server__pubmed_search_articles` + WebFetch on PubMed |
+| **Zotero** | User's local library (closed-access journals) | `mcp__zotero__zotero_search_items`, `zotero_get_item_fulltext` |
+| **Crossref** | DOI verification | WebFetch on `api.crossref.org/works/<DOI>` |
+
+For closed-access journals (Med Image Anal, Eur Radiol, Lancet family) the user's local Zotero library is often the only path. Always check Zotero before assuming a paper is inaccessible.
+
+For MCP server configuration, see [references/MCP_SETUP.md](references/MCP_SETUP.md).
+
+---
+
+## Reference Files
+
+| File | Read when |
+|---|---|
+| [references/WORKFLOW.md](references/WORKFLOW.md) | Starting a new review or moving between phases |
+| [references/PARADIGM.md](references/PARADIGM.md) | Phase 0: capturing exemplar review style spec |
+| [references/CITATION_INTEGRITY.md](references/CITATION_INTEGRITY.md) | Phase 2 (collection) and Phase 4 (write) — every citation must follow the 5 rules |
+| [references/HALLUCINATION_PATTERNS.md](references/HALLUCINATION_PATTERNS.md) | Phase 4 (write) and Phase 5 (peer review) — checklist of 9 LLM hallucination indicators to self-check against |
+| [references/DOMAINS.md](references/DOMAINS.md) | Phase 3 (outline) — 3-axis method groupings per domain |
+| [references/TEMPLATES.md](references/TEMPLATES.md) | Phase 1 (init) — CLAUDE.md, IMPLEMENTATION_PLAN.md, table templates |
+| [references/QUALITY_CHECKLIST.md](references/QUALITY_CHECKLIST.md) | Before delivering a draft to the user |
+| [references/MCP_SETUP.md](references/MCP_SETUP.md) | Setting up arxiv-mcp / pubmedmcp / zotero-mcp |
+
+---
+
+## Related Skills
+
+For revising an existing AI-drafted review (whether your own previous output or someone else's draft), use `ai-review-revision`. That skill is the dedicated tool for fixing draft-quality issues — multi-agent diagnostic, factual reset, structural reset, content polish, submission prep.
+
+This skill (`medical-imaging-review`) is the dedicated tool for producing draft-quality content correctly the first time. They are complementary:
+
+- **medical-imaging-review** = write-side (produce submission-quality first draft)
+- **ai-review-revision** = revise-side (rescue a draft that already has quality issues)
+
+If a draft produced by this skill still ends up needing the `ai-review-revision` workflow to land, that's a bug — flag it so this skill can be improved.
+
+---
+
+## Why this skill was rewritten (v3 vs v2)
+
+v2.0.0 produced the `coronary-cta-paper` initial draft. That draft needed extensive multi-day revision before submission-readiness: 17 placeholder DOIs, 30-40 [N] citation drift errors, fabricated method module names with wrong performance numbers, vendor-style citations attributed to peer-reviewed journals, a 10-subsection flat method taxonomy where 3 thematic axes would have served better, AI-tone hedging language throughout.
+
+v3 directly addresses each of these failure modes:
+
+| v2 failure | v3 fix |
+|---|---|
+| Hedging mandate in Core Principles | Removed; replaced with "match voice to evidence" |
+| 80-120 reference count target | Removed; replaced with "cite what supports the argument" |
+| Method fill-in template | Removed; replaced with "read-first, write-after" discipline |
+| 10-flat method subsection taxonomy | Replaced with 3-axis grouping in DOMAINS.md |
+| QA = formal structural check | Replaced with per-claim verification embedded in Phase 4 |
+| No DOI / author / direction verification | Added as CITATION_INTEGRITY.md with 5 rules |
+| No hallucination self-check | Added as HALLUCINATION_PATTERNS.md (9 patterns) |
+| Numbered headings | Banned; max 2 levels, bold lead-in for deeper |
+| Vendor names scattered | Confined to Table 3 only |
+| Equations inline | Confined to Box 1 only |
+| Verdict-free neutral catalogue | Required 3-5 verdict sentences |
+| No exemplar paradigm capture | Added Phase 0 PARADIGM.md |

package/dist/skills/medical-imaging-review/references/CITATION_INTEGRITY.md

@@ -0,0 +1,233 @@
+# Citation Integrity Protocol
+
+This is the most important reference file in the skill. Citation drift / fabrication is the #1 failure mode of LLM-drafted reviews.
+
+5 rules. Every citation must satisfy all 5.
+
+---
+
+## Rule 1: No placeholder DOIs
+
+Any DOI containing `xxx`, `[TBD]`, `?`, stub patterns, or "to-be-filled" notation **must be resolved before the manuscript advances to the next section**.
+
+### Detection
+
+```bash
+grep -nE "xxx|\[TBD\]|x\):xxx|doi:10\.[a-z]+/x" manuscript_draft.md
+```
+
+Expected: 0 hits at any milestone.
+
+### Resolution
+
+For papers with a PMID:
+
+```
+WebFetch on https://pubmed.ncbi.nlm.nih.gov/<PMID>/
+  → Extract: title, full author list, journal, year, volume, issue, pages, DOI
+```
+
+For papers without a PMID but a known DOI:
+
+```
+WebFetch on https://api.crossref.org/works/<DOI>
+  → Extract: same fields from JSON
+```
+
+For papers in a closed-access journal where the user has the PDF:
+
+```
+mcp__zotero__zotero_search_items(query: "<author> <method>")
+mcp__zotero__zotero_get_item_metadata(item_key: ...)
+```
+
+### Why this is Rule 1
+
+v2 of this skill shipped 17 placeholder DOIs in the coronary-cta-paper draft. Editors at any medical journal will reject a manuscript with `xxx` in the DOI on first sight. This is the lowest-effort, highest-impact rule.
+
+---
+
+## Rule 2: Author list verification
+
+Every reference in the bibliography must have its first and last author verified against the first-source. For references with > 6 authors, list first 6 + et al. — but the first author (and last author for medical clinical papers) must be verbatim.
+
+### LLM failure mode
+
+LLMs generate **generic-sounding 4-author lists** when they don't know the actual authors:
+
+- ✗ "Liu Y, Zhang H, Chen X, Wang J. TransCC..." (these are common Chinese surnames in 4-author pattern — strong fabrication signal)
+- ✗ "Smith J, Johnson A, Williams M, Brown D" (English equivalent)
+- ✗ "Patel R, Kumar A, Singh P, Sharma N"
+
+### Detection
+
+For each reference in the bibliography, ask:
+- Are these 4 of the most common surnames in a major language?
+- Do the initials look suspiciously "average" (J / A / M / D)?
+- Is this a paper where I might have looked up the title but never the authors?
+
+For any "yes" answer, treat as suspect and verify.
+
+### Resolution
+
+```
+WebFetch on https://pubmed.ncbi.nlm.nih.gov/<PMID>/
+  OR
+WebFetch on https://api.crossref.org/works/<DOI>
+  → Replace the entire author list verbatim.
+```
+
+For arXiv papers:
+
+```
+WebFetch on https://arxiv.org/abs/<id>
+```
+
+### Why this matters
+
+A wrong author list reads as obvious fabrication to anyone in the field. Real reviewers know the principal investigators in their area, and seeing "Liu Y, Zhang H, Chen X, Wang J" attached to a high-profile method paper is an instant credibility kill.
+
+---
+
+## Rule 3: Body ↔ Bibliography reconciliation
+
+The `[N]` in the body must (a) exist in the bibliography and (b) be the paper the body sentence is actually attributing the claim to.
+
+### LLM failure mode — "citation drift"
+
+When LLM reorganizes sections or merges paragraphs, it often forgets to renumber citations. The body sentence says "Shit et al. introduced clDice [43]" but bibliography entry [43] is a completely different paper (e.g., a centerline DRL paper). Bibliography entry [10] is actually the clDice paper.
+
+### Detection
+
+```bash
+# Find all citations in body
+grep -nE "\[([0-9]+)\]" manuscript_draft.md | head -50
+
+# Find bibliography entries
+grep -nE "^[0-9]+\." manuscript_draft.md
+```
+
+For each body citation `[N]`, verify:
+- Is there a bibliography entry numbered N?
+- Does that entry attribute to the right paper?
+
+### Resolution
+
+Two patterns:
+
+**Pattern A: Single-author misattribution.** Body says "Shit et al. [43]" but [43] is wrong. Action: `grep -n "Shit"` to find the correct number, edit body to point there.
+
+**Pattern B: Numerical drift across many citations.** Body [60] should be [36] (after section reorganization shifted 24 entries). Action: list affected range, manually re-number.
+
+For a typical 120-reference review, expect 5-15 drift instances if you're careful and 30-40 if you're not.
+
+### Detection at scale
+
+Build a verification script:
+
+```python
+# Pseudocode
+for n in body_citations:
+    bib_entry = bibliography.get(n)
+    body_sentence = sentence_containing(n)
+    body_author = extract_author_mention(body_sentence)
+    bib_author = extract_first_author(bib_entry)
+    if body_author and bib_author and body_author.lower() not in bib_author.lower():
+        flag(n, body_author, bib_author)
+```
+
+---
+
+## Rule 4: Conclusion-direction verification
+
+For every cited **finding** (HR, OR, p-value, effect size, "higher" / "lower" claim), the body sentence's directional claim must match the source's stated direction.
+
+### LLM failure mode
+
+LLMs flip directions when paraphrasing. The paper says "patients with collateral circulation had **lower** FAI values." LLM paraphrase becomes: "Lv et al. [N] showed collateral circulation is associated with **higher** FAI."
+
+This is one of the worst failures because the cited paper genuinely exists, the author is real, and the topic is right — but the conclusion direction is reversed. Catches eye of any reviewer in the area.
+
+### Detection
+
+For every body sentence that contains directional language (higher / lower / increased / decreased / better / worse), the writer must have explicitly verified the direction against the source.
+
+Quick checklist when writing such a sentence:
+1. What direction does the source actually report?
+2. What direction am I about to write?
+3. Do those match?
+
+### Resolution
+
+Always cite directions verbatim from the abstract. Don't paraphrase quantitative directional claims.
+
+✗ "Lv et al. [N] showed collaterals are associated with higher FAI."
+✓ "Patients with collateral circulation had lower FAI values than those without (Lv et al. [N])."
+
+---
+
+## Rule 5: First-source over vendor materials
+
+Vendor white papers, NHS England reports, FDA 510(k) clearance letters, and company press releases are **not** peer-reviewed primary sources for clinical findings. Cite them only for regulatory facts (clearance date, indication), not for clinical evidence (trial results, performance numbers).
+
+### LLM failure mode
+
+LLM cites "NHS England. FISH&CHIPS Study Implementation Report. BMJ Open. 2024" as if it's a peer-reviewed trial. Reality: there is no such BMJ Open paper. The FISH&CHIPS study is a real NHS program, and its peer-reviewed publication is:
+
+> Fairbairn TA, Mullen L, Nicol E, Lip GYH, Schmitt M, Shaw M, et al. Implementation of a national AI technology program on cardiovascular outcomes and the health system. **Nat Med**. 2025;31(6):1903-1910.
+
+The body sentence was right about the study existing, but the citation was a fabricated journal attribution.
+
+### Detection
+
+For every reference that looks like:
+- "[Company name]. [Product] White Paper. ..."
+- "[Agency]. [Study]. ..."
+- "[Study Investigators]. [Findings]. [Major journal]. 2024."
+
+Treat as **suspect** and search for the actual peer-reviewed publication.
+
+### Resolution
+
+For each vendor- or agency-style citation, search PubMed:
+
+```
+mcp__pubmed-mcp-server__pubmed_search_articles(query: "<study acronym> implementation OR validation")
+```
+
+If a peer-reviewed publication exists, use it. If not, use the vendor material **only for regulatory / programmatic facts**, never for clinical performance claims.
+
+---
+
+## Verification Workflow Integration
+
+These 5 rules are applied at multiple points:
+
+| Phase | Rules applied | How |
+|---|---|---|
+| Phase 2 (collection) | Rules 1, 2, 5 | At entry time, before adding to bibliography |
+| Phase 4 (writing) | Rules 1, 3, 4 | Per-paragraph as citations are placed |
+| Phase 5 (peer review) | All 5 | `ref-checker` teammate runs systematic pass |
+| Phase 6 (submission) | All 5 | Final checklist before submission |
+
+---
+
+## What to do when a rule failure is found
+
+Failures are normal — these are guardrails, not aspirational goals.
+
+For each failure:
+
+1. **Stop forward writing immediately.** Don't accumulate broken citations.
+2. **Look up the correct metadata** using the resolution steps above.
+3. **Fix the citation in place** — body sentence + bibliography entry both.
+4. **Check for related failures.** A misattribution in one place often signals the same error in 2-3 other places where the same paper was cited.
+5. **Log the fix** in `IMPLEMENTATION_PLAN.md` change log — this protects the next person editing the manuscript.
+
+---
+
+## Why this protocol exists
+
+The single largest source of credibility damage in LLM-drafted reviews is citation infrastructure failure. A draft can have brilliant analysis and miss editor first-glance if the bibliography is fabricated, drifted, or misattributed.
+
+This protocol takes 10-20% of total writing time but eliminates 80%+ of the credibility-killer issues. It is non-negotiable.