medsci-skills 4.1.0

package/skills/write-paper/references/paper_types/original_article.md

@@ -0,0 +1,221 @@
+# Original Article — IMRAD Template
+
+## Overview
+
+Standard template for medical original research articles. Follows the Introduction, Materials and Methods, Results, and Discussion (IMRAD) structure used by virtually all biomedical journals.
+
+---
+
+## Title
+
+- Concise and specific, under 20 words.
+- Include the study design if space allows (e.g., "A Retrospective Cohort Study").
+- Avoid questions, abbreviations (except universally known ones like CT, MRI, AI), and clever wordplay.
+- Good: "Deep Learning Detection of Pulmonary Embolism on CT Angiography: A Multicenter Validation Study"
+- Bad: "Can AI Find Clots? A Novel Approach Using Advanced Neural Networks"
+
+---
+
+## Abstract (Structured, 250 words max)
+
+Four sections matching the journal's required headings (common variants shown):
+
+### Purpose / Objective
+- One to two sentences stating the study aim.
+- Template: "To {evaluate/compare/assess/determine} {what} in {population/context}."
+
+### Materials and Methods
+- Study design, setting, dates, participants (N), key methods, primary outcome measure, statistical approach.
+- Three to four sentences maximum.
+
+### Results
+- Key findings with specific numbers (effect sizes, CIs, p-values).
+- Start with primary endpoint, then most important secondary findings.
+- Three to four sentences maximum.
+
+### Conclusion
+- One to two sentences. Restate the main finding and its implication.
+- Do NOT end with "further studies are needed."
+- Be specific: "This model achieved diagnostic accuracy comparable to fellowship-trained radiologists and may reduce interpretation time for emergency CT studies."
+
+---
+
+## Introduction (3-4 paragraphs, ~400-500 words)
+
+### Paragraph 1: Clinical Context
+- Establish the clinical importance of the topic.
+- Cite prevalence, incidence, or burden data.
+- Describe current clinical practice or diagnostic approach.
+
+### Paragraph 2: Knowledge Gap
+- What is known from prior work (cite key studies).
+- What remains unknown, uncertain, or unresolved.
+- Why this gap matters clinically.
+
+### Paragraph 3: Study Objective
+- State the specific aim of this study.
+- Include hypothesis if applicable (for confirmatory studies).
+- Template: "The purpose of this study was to {aim}. We hypothesized that {hypothesis}."
+- Optional final sentence previewing the approach: "We evaluated this in a {study design} of {N} patients at {setting}."
+
+### Rules
+- Do not review the entire literature; cite only what is needed to establish the gap.
+- Do not describe methods or results.
+- Do not state conclusions.
+- Funnel structure: broad context to narrow focus.
+
+---
+
+## Materials and Methods (~800-1200 words)
+
+### 3.1 Study Design and Setting
+- One paragraph: design (retrospective/prospective, single/multicenter), institution(s), date range.
+- Template: "This {retrospective cohort / prospective cross-sectional / etc.} study was conducted at {institution} between {start date} and {end date}."
+
+### 3.2 Participants / Study Population
+- Inclusion and exclusion criteria, stated explicitly.
+- How participants were identified (database query, consecutive enrollment, random sampling).
+- Final sample size with brief explanation of exclusions.
+- For AI studies: dataset split (training/validation/test) with rationale.
+
+### 3.3 Procedures / Intervention / Index Test
+- Describe what was done in enough detail for replication.
+- For imaging: scanner model, sequence parameters, contrast protocol.
+- For AI: model architecture, input data, preprocessing, training procedure, hyperparameters.
+- For reader studies: number of readers, experience level, blinding, reading environment.
+
+### 3.4 Outcome Measures
+- Define primary and secondary endpoints explicitly.
+- State the reference standard and how it was established.
+- Define any composite endpoints or derived variables.
+
+### 3.5 Statistical Analysis
+- Descriptive statistics approach (mean +/- SD or median [IQR]).
+- Specific tests for each comparison (name the test, state the rationale).
+- Significance level (two-sided, alpha = 0.05).
+- Software and version.
+- Sample size justification if applicable.
+- See `section_templates/methods_statistical.md` for common paragraph templates.
+
+### 3.6 Ethics
+- IRB/Ethics committee approval (name, protocol number).
+- Informed consent status (obtained, waived with reason).
+- For retrospective studies: "The institutional review board of {institution} approved this retrospective study and waived the requirement for informed consent."
+
+---
+
+## Results (~800-1200 words)
+
+### 4.1 Study Population
+- Start with the total number screened, excluded (with reasons), and included.
+- Reference the flow diagram (Figure 1) if applicable.
+- Describe demographics and baseline characteristics, referencing Table 1.
+- Template: "A total of {N} patients ({N} male, {N} female; mean age, {X} +/- {Y} years) were included."
+
+### 4.2 Primary Endpoint
+- Present the main result with effect size and 95% CI.
+- Reference the relevant table or figure.
+- Template: "The {metric} was {value} (95% CI, {lower}-{upper}; P = {value})."
+
+### 4.3 Secondary Endpoints
+- Present in order of importance or in the order listed in Methods.
+- Each gets its own paragraph or sub-paragraph.
+
+### 4.4 Subgroup and Sensitivity Analyses
+- Present if pre-specified in Methods.
+- Acknowledge if exploratory (not powered for subgroup differences).
+
+### Rules
+- Do NOT interpret findings; state them. Results answers "What?" only — never "Why?"
+- Every table and figure must be referenced in the text.
+- Numbers in text must match tables exactly.
+- Report exact p-values; use "P < .001" only when truly below 0.001.
+- Present data in the same order as Methods subsections.
+- NO comparisons with prior literature (save for Discussion).
+- NO causal language ("caused," "led to," "due to") — use "was associated with."
+- NO evaluative adjectives without numbers ("high," "notable," "remarkable").
+- NO hedge words implying interpretation ("suggests," "implies," "indicates importance").
+- Banned openers: "Interestingly," "Notably," "Remarkably," "Surprisingly," "As expected."
+
+---
+
+## Discussion (4-5 paragraphs, ~800-1200 words)
+
+> **Before writing:** The user should provide anchor papers (3-5 key references for
+> comparison) and key findings to emphasize. See SKILL.md Phase 5a for the interactive
+> planning gate. If not provided, identify anchor papers from the reference list.
+
+### Paragraph 1: Summary of Key Findings
+- Restate the principal findings in the context of the study aim.
+- Do not repeat exact numbers from Results (paraphrase).
+- One paragraph, 3-5 sentences.
+
+### Paragraphs 2-3: Comparison with Prior Literature (anchor paper driven)
+- Organize around anchor papers provided by the user.
+- For each anchor paper: state their finding → compare with ours → explain discrepancy.
+- Pattern: "Smith et al. [ref] reported {X} in {population}. In contrast/Similarly, our
+  study found {Y}, which may be attributable to {methodological/population difference}."
+- Include both concordant and discordant studies.
+
+### Paragraph 4: Clinical Implications
+- What does this mean for clinical practice, training, or future research?
+- Be specific: "{AI tool} could be integrated into {specific workflow} to {specific benefit}."
+- Avoid vague statements about "future directions."
+
+### Paragraph 5: Limitations
+- Ordered by severity (most impactful first).
+- Be specific and honest.
+- Do NOT start with "Our study has several limitations."
+- For each limitation: (a) what it is, (b) how it was mitigated, (c) direction of residual bias.
+- Template: "This study has limitations. First, the retrospective design at a single
+  institution limits generalizability; however, the multicenter external test set partially
+  addresses this, and any selection bias would likely inflate performance estimates."
+
+### Conclusion (within Discussion, final paragraph or sentence)
+- One to two sentences restating the single most important finding.
+- Must be a citable statement — memorable and specific.
+- Template: "In summary, {main finding} in {context}, suggesting {implication}."
+
+---
+
+## References
+
+- Typically 30-40 for original articles.
+- Prioritize recent references (within 5 years) for establishing current knowledge.
+- Include seminal/classic references where appropriate.
+- Every citation must be referenced in the text.
+- Self-citation should be limited and justified.
+
+---
+
+## Tables
+
+- **Table 1**: Demographics and baseline characteristics (always required).
+  - Columns: overall cohort, comparison groups (if applicable).
+  - Rows: age, sex, relevant clinical variables.
+  - Include p-values for between-group comparisons if relevant.
+- **Table 2+**: Results tables (primary/secondary endpoints, model performance, etc.).
+- Use footnotes for abbreviations and statistical details.
+- Do not duplicate data that is better shown in a figure.
+
+## Figures
+
+- **Figure 1**: Flow diagram (CONSORT/STARD/PRISMA as appropriate).
+- Additional figures: performance curves (ROC, calibration), representative images, forest plots.
+- Each figure needs a descriptive legend that allows the figure to be understood without reading the text.
+- Minimum 300 dpi resolution for submission.
+
+---
+
+## Checklist Before Submission
+
+- [ ] Title under 20 words, specific and informative
+- [ ] Abstract numbers match Results/Tables
+- [ ] Introduction ends with clear objective
+- [ ] Methods sufficient for replication
+- [ ] All tables/figures referenced in text
+- [ ] Numbers consistent between text, tables, and figures
+- [ ] Limitations discussed honestly
+- [ ] All reporting guideline items addressed
+- [ ] References complete and correctly formatted
+- [ ] Word count within journal limits

package/skills/write-paper/references/paper_types/technical_note.md

@@ -0,0 +1,131 @@
+# Paper Type: Technical Note
+
+## Overview
+
+- **Purpose:** Describe a novel technique, method, algorithm, or device — NOT clinical outcomes
+- **Typical word count:** 1500–2500 words
+- **Structure:** Abstract (unstructured or brief structured) → Introduction → Materials and Methods → Results (proof of concept) → Discussion → Conclusion
+- **Key requirement:** Sufficient reproducibility data; must demonstrate feasibility, not efficacy
+
+---
+
+## What a Technical Note Is (and Is Not)
+
+**IS:** A concise description of a new technique, workflow, algorithm, software tool, or modified procedure, with proof-of-concept validation data.
+
+**IS NOT:** A clinical efficacy study. Technical notes do not aim to demonstrate that a new technique is better than existing ones — that requires a full original article with appropriate controls and statistical power.
+
+---
+
+## Abstract (150–200 words, unstructured or brief structured)
+
+"We describe [technique/method/tool] for [application]. [One sentence on how it works]. Using [validation dataset / N cases / N samples], we demonstrated [key performance metric with value]. [One sentence on potential clinical or research utility]. [This technique is available / Code is available at [URL]]."
+
+---
+
+## Introduction (300–500 words)
+
+1. **Clinical or research problem:** Why is a new technique needed? What is the limitation of existing methods?
+2. **Description of the new approach:** Brief overview without technical detail (that belongs in Methods).
+3. **Objective:** "The purpose of this technical note is to describe [technique] and demonstrate its feasibility in [application context]."
+
+---
+
+## Materials and Methods (600–1000 words)
+
+This is the core of the technical note. Write in enough detail that the technique can be replicated by another group.
+
+### System/Technique Description
+
+Describe the method step by step. Use numbered steps or clear paragraphs. Include:
+
+**For imaging techniques:**
+- Equipment (manufacturer, model, software version)
+- Acquisition parameters (field strength, sequence parameters, slice thickness, FOV, contrast agent if used)
+- Post-processing steps
+- Analysis software and version
+
+**For software/algorithm:**
+- Programming language and version (e.g., Python 3.10, PyTorch 2.0.1)
+- Architecture description (high-level; detailed architecture in supplementary)
+- Training/validation/test split
+- Computational requirements (GPU, RAM, processing time per case)
+- Availability: "Code is publicly available at [GitHub URL] under [license]"
+
+**For procedural techniques:**
+- Equipment, instruments, materials (with catalog numbers if novel)
+- Step-by-step procedure
+- Safety considerations and failure modes
+
+### Validation Dataset
+
+- Source: retrospective or prospective, single center
+- N cases / samples
+- Inclusion/exclusion criteria (brief)
+- Reference standard used for comparison (if applicable)
+
+### Evaluation Metrics
+
+Define exactly what you measured and how:
+- For segmentation: Dice similarity coefficient, Hausdorff distance
+- For detection: sensitivity, specificity at fixed operating point
+- For measurement tools: ICC with 95% CI against reference method (Bland-Altman analysis)
+- For image quality: signal-to-noise ratio, contrast-to-noise ratio, or expert reader assessment
+
+State how reproducibility was assessed (intra- and inter-observer variability).
+
+---
+
+## Results (400–600 words — Proof of Concept)
+
+Report the key feasibility metrics. This section should be concise.
+
+- Success rate (technical feasibility)
+- Primary performance metric with 95% CI
+- Processing time (if relevant)
+- Any failure cases and their characteristics
+
+"The technique was successfully applied in [N/N] ([%]) cases. [Primary metric] was [value] (95% CI, [lower]–[upper]). Mean processing time per case was [X ± SD] seconds on a [hardware specification]."
+
+If comparing to an existing reference method:
+"Compared with [reference method], [new technique] demonstrated [similar/higher/lower] [metric] ([value] vs. [value]; difference, [X]; 95% CI, [lower]–[upper]; P = [value])."
+
+---
+
+## Discussion (300–500 words)
+
+1. **Summary of findings:** What did you demonstrate? Keep to feasibility.
+2. **Technical advantages:** What does this technique offer that existing approaches do not?
+3. **Limitations:**
+   - Small validation set (cannot make efficacy claims)
+   - Single-center, single-vendor
+   - May not generalize (state conditions under which technique may fail)
+   - Computational requirements (if any)
+4. **Future directions:** What clinical validation is needed? Will you make the tool publicly available?
+
+---
+
+## Conclusion (50–100 words)
+
+"We describe [technique] for [application]. Proof-of-concept validation in [N] [cases/samples] demonstrated [key metric]. This technique [potential utility]. [Clinical validation in larger prospective studies is warranted]."
+
+---
+
+## Supplementary Materials
+
+Technical notes commonly require supplementary materials:
+- Detailed algorithm pseudocode or flowchart
+- Full acquisition parameter tables
+- Additional validation cases (figures)
+- Code repository link + usage instructions
+
+---
+
+## Common Technical Note Pitfalls
+
+1. **Making efficacy claims instead of feasibility claims** — a technical note cannot conclude that the technique is better; say it "demonstrates feasibility" or "warrants further investigation."
+2. **Missing reproducibility data** — always report intra- and inter-observer variability (ICC) for measurement tools.
+3. **Insufficient Methods detail** — another lab must be able to replicate from your Methods alone.
+4. **Not specifying software versions** — exact versions are required for reproducibility.
+5. **Combining technical note and clinical study** — keep the paper focused; add clinical data in supplementary only if very limited.
+6. **No code availability statement** — increasingly expected for algorithm papers; GitHub link strongly encouraged.

package/skills/write-paper/references/section_guides/discussion.md

@@ -0,0 +1,155 @@
+# Discussion Writing Guide
+
+Reference for write-paper Phase 5 (Discussion).
+Loaded on-demand when drafting the Discussion section.
+
+---
+
+## Purpose
+
+Discussion answers: "Why do these results matter?" It connects your findings to
+the broader clinical and scientific context. Results tells the reader *what* you found;
+Discussion tells them *so what*.
+
+---
+
+## Specifications
+
+- **Word limit**: 800 words for Radiology; check journal profile for others
+- **No Table/Figure citations**: Do not reference Tables or Figures in Discussion
+  (journal-specific — verify with loaded profile, but this is the default for Radiology)
+- **No abbreviations**: In the first and last paragraphs, spell out all abbreviations
+- **Structure**: 4-paragraph base (expandable to 5-6 for complex studies)
+
+---
+
+## 4-Paragraph Structure
+
+### Paragraph 1: Summary of Key Findings
+
+- 2-3 sentences restating the main findings
+- Include the primary metric with its value (but do not repeat all numbers verbatim from Results)
+- End with one sentence on clinical importance or implication
+
+**Template**:
+```
+In this study, we evaluated [what was done].
+We found that [main finding with key metric].
+[Optional: secondary finding].
+This finding suggests [core clinical interpretation in one sentence].
+```
+
+### Paragraphs 2-3 (or 2-4): Interpretation and Literature Comparison
+
+- Organize by theme or finding, not by reviewer expectation
+- Order by importance: most significant finding first
+- For each comparison with prior work:
+  1. State the prior finding with citation
+  2. State whether your result agrees or disagrees
+  3. If disagrees: explain the discrepancy (methodological or population differences)
+- For unexpected results: offer a plausible explanation backed by references
+
+**Rules**:
+- Do not list prior studies mechanically ("A found X. B found Y. C found Z.")
+- Only cite studies that directly relate to your findings — not tangential background
+- Prefer high-impact journal references for comparisons
+- Do not attack or disparage prior studies; present differences neutrally
+- Speculation is acceptable if flagged as such and supported by a reference
+
+### Limitation Paragraph
+
+This is the most scrutinized paragraph. Write it with care.
+
+**Tone: frank and objective**
+- Acknowledge real limitations honestly
+- Do not bury limitations under a pile of strengths
+- Do not be self-deprecating either — state facts
+
+**Structure for each limitation**:
+1. What the limitation is
+2. How it was mitigated (if at all)
+3. What direction of bias it introduces (overestimate or underestimate)
+
+**Checklist-guided limitations** (check the relevant guideline):
+- **STROBE (cohort)**: Potential bias direction, generalizability
+- **TRIPOD (prediction)**: Sample size, overfitting, missing data, data quality
+- **STARD (diagnostic)**: Spectrum bias, verification bias, reader experience
+
+**What NOT to do**:
+- Do not open with "Our study has several limitations" (generic; dive straight in)
+- Do not list 6+ limitations — 3-4 is sufficient for most studies
+- Do not neutralize every limitation with "however, our study also has strengths"
+  (a few strengths at the end are fine, but limitation-strength-limitation-strength
+  ping-pong reads as defensive)
+
+**Last sentence**: A future study recommendation is acceptable here.
+
+**Study-design-specific limitation templates**:
+
+- **Healthy volunteer / screening cohort bias**: Participants in voluntary health screening programs tend to be healthier, more health-conscious, and of higher socioeconomic status than the general population. This selection bias may limit generalizability and likely underestimates event rates compared to population-based cohorts. Mitigations: report the cohort's baseline characteristics against national statistics; acknowledge the direction of bias explicitly.
+- **Surveillance bias (repeated screening)**: Participants with more frequent follow-up visits have higher probability of outcome detection. If the number of follow-up visits differs between groups, this asymmetry may inflate apparent event rates in the more-screened group. Report the number of scans/visits per participant (median, IQR) and note any group imbalance in surveillance intensity.
+
+### Conclusion (Final Paragraph or Final Sentences)
+
+- Must align with the Purpose statement from the Introduction
+- State only conclusions directly supported by Results (no over-interpretation)
+- End with a clinical implication or application, not "further studies are needed"
+- Should be a citable, quotable statement
+
+---
+
+## Relationship with Introduction
+
+Discussion and Introduction are a conversation:
+- Introduction foreshadows the gap
+- Discussion fills that gap with your findings
+
+The reader should be able to read the Introduction's gap statement and the Discussion's
+conclusion and see a direct logical connection. If they do not connect, either the
+Introduction was too broad or the Discussion overclaims.
+
+---
+
+## Common Mistakes
+
+1. **Repeating Results**: Restating numbers without adding interpretation
+2. **Wandering off-topic**: Discussing tangential findings not in your Results
+3. **Introducing new data**: Mentioning analyses not presented in Results
+   (if needed, add to Supplementary first, then reference)
+4. **Over-interpretation**: Claiming causation from observational data
+5. **Too long**: Exceeding word limits signals lack of focus
+6. **Literature dump**: Paragraphs of prior study summaries with no connection to your findings
+7. **Defensive limitation writing**: Every limitation immediately countered with a strength
+8. **Ignoring contradictory evidence**: Not addressing studies that found opposite results
+
+---
+
+## Stuckler's Alternative Structure (for non-radiology journals)
+
+Some journals or fields prefer limitations before interpretation:
+
+1. **Recap of findings**
+2. **Limitations** (early — "psychologically unblock the reader")
+3. **Strengths**
+4. **Coherence with literature**
+5. **Implications for future research**
+
+Rationale: addressing limitations first disarms the reader's skepticism, making them
+more receptive to your interpretation. Consider this structure for journals outside
+the radiology tradition.
+
+---
+
+## Self-Check
+
+Before finalizing Discussion:
+
+- [ ] Within word limit (800 words for Radiology)?
+- [ ] No Table/Figure citations in Discussion?
+- [ ] No abbreviations in first and last paragraphs?
+- [ ] Key findings summarized (not just repeated)?
+- [ ] Each comparison with prior work includes: their finding, agreement/disagreement, explanation?
+- [ ] Limitations are honest, specific, and include bias direction?
+- [ ] Conclusion matches the Introduction's purpose statement?
+- [ ] No new data introduced that is not in Results?
+- [ ] No AI pattern phrases ("plays a crucial role", "sheds light on")?

package/skills/write-paper/references/section_guides/introduction.md

@@ -0,0 +1,108 @@
+# Introduction Writing Guide
+
+Reference for write-paper Phase 6 (Introduction + Abstract).
+Loaded on-demand when drafting the Introduction section.
+
+---
+
+## Specifications
+
+- **Word count**: 300-400 words (most radiology journals)
+- **Paragraphs**: 3-4
+- **References**: 10-15 citations
+- **Tense**: Present tense for established knowledge; past tense for specific prior study findings
+- **Structure**: Funnel shape — broad context narrowing to specific gap and study objective
+
+---
+
+## Gap Storytelling: 5-Step Structure
+
+The Introduction is a story that leads the reader inevitably to your research question.
+The GAP is the single most important element — it determines accept vs. reject more than
+methodology alone.
+
+### Step 1: Disease Burden and Clinical Significance
+
+Establish why this topic matters. Cite prevalence, clinical impact, or current practice gaps.
+Keep it to 2-3 sentences — do not write a textbook introduction.
+
+### Step 2: Existing Research Landscape
+
+Summarize what is already known. Do NOT list studies mechanically ("Study A found X.
+Study B found Y."). Instead, weave them into a narrative that builds toward the gap.
+
+### Step 3: Most Relevant Prior Work (1-2 studies)
+
+Highlight the closest prior work to your study. Describe what they did and what they
+achieved. This sets the benchmark your study will build upon or challenge.
+
+### Step 4: The GAP (critical)
+
+State clearly what remains unknown, unsolved, or insufficient. This is the pivot point
+of the entire Introduction.
+
+Effective gap statements:
+- "However, [prior approach] has not been validated in [your population/setting]."
+- "Whether [finding] applies to [specific subgroup] remains unclear."
+- "No study has directly compared [A] and [B] in [context]."
+
+Weak gap statements (avoid):
+- "There is limited research on..." (vague)
+- "No study has ever..." (too absolute — likely incorrect)
+- "The role of X is not fully understood" (every topic could claim this)
+
+### Step 5: Study Objective
+
+State the specific aim: "Therefore, the purpose of this study was to..."
+
+- Use "purpose" or "aim" — avoid "goal" or "objective" interchangeably within one paper
+- Match the objective precisely to the gap
+- If there is a hypothesis, state it explicitly
+
+---
+
+## Three-Part Formula (complementary framing)
+
+An alternative lens for the same structure (from academic writing pedagogy):
+
+1. **The Debate**: Why should the reader care right now? What is the burning question?
+2. **The Gap**: What do we know, and what is still missing?
+3. **The Winning Study**: How does this study fill that gap?
+
+This maps directly to Steps 1-2, Step 4, and Step 5 above.
+
+---
+
+## Common Mistakes
+
+1. **Too much background**: Spending 200+ words on disease epidemiology before reaching the gap
+2. **Mechanical literature listing**: "A et al. found X. B et al. found Y. C et al. found Z."
+3. **Vague gap**: "Limited research exists" without specifying what specifically is unknown
+4. **Mismatch**: Gap statement does not logically lead to the study objective
+5. **Over-promising**: Implying the study will solve a problem it cannot address
+6. **Too many references**: Citing 25+ references in the Introduction signals unfocused writing
+
+---
+
+## Gap Discovery Strategies
+
+When struggling to articulate the gap:
+
+1. Read the Discussion "future research" sections of related papers — authors explicitly state gaps
+2. Read systematic review limitation sections — reviewers synthesize what is missing
+3. Check if prior work was done in a different population, modality, or clinical setting
+4. Look for methodological limitations in prior studies that your design addresses
+
+---
+
+## Self-Check
+
+Before finalizing the Introduction:
+
+- [ ] 300-400 words?
+- [ ] 3-4 paragraphs?
+- [ ] 10-15 references?
+- [ ] Gap is specific, concrete, and compelling?
+- [ ] Study objective directly follows from the gap?
+- [ ] No AI pattern phrases ("In the rapidly evolving landscape of...")?
+- [ ] Funnel structure maintained (broad → narrow)?