write-paper

Files (118)

• SKILL.md
• exemplar_abstract.md · references/
• exemplar_case_report.md · references/
• exemplar_case_report_radiology.md · references/
• README.md · references/exemplar_discussion/
• ai_validation_tripod_claim.md · references/exemplar_discussion/
• diagnostic_accuracy_stard.md · references/exemplar_discussion/
• meta_analysis_prisma.md · references/exemplar_discussion/
• observational_cohort_strobe.md · references/exemplar_discussion/
• rct_consort.md · references/exemplar_discussion/
• exemplar_introduction.md · references/
• README.md · references/exemplar_methods/
• ai_validation_tripod_claim.md · references/exemplar_methods/
• diagnostic_accuracy_stard.md · references/exemplar_methods/
• meta_analysis_prisma.md · references/exemplar_methods/
• observational_cohort_strobe.md · references/exemplar_methods/
• rct_consort.md · references/exemplar_methods/
• README.md · references/exemplar_results/
• ai_validation_tripod_claim.md · references/exemplar_results/
• diagnostic_accuracy_stard.md · references/exemplar_results/
• meta_analysis_prisma.md · references/exemplar_results/
• observational_cohort_strobe.md · references/exemplar_results/
• rct_consort.md · references/exemplar_results/
• AJKD.md · references/journal_profiles/
• AJNR.md · references/journal_profiles/
• AJR.md · references/journal_profiles/
• Abdominal_Radiology.md · references/journal_profiles/
• Academic_Radiology.md · references/journal_profiles/
• Annals_of_Internal_Medicine.md · references/journal_profiles/
• Annals_of_Oncology.md · references/journal_profiles/
• Artificial_Intelligence_in_Medicine.md · references/journal_profiles/
• British_Journal_of_Radiology.md · references/journal_profiles/
• CVIR.md · references/journal_profiles/
• Cancer_Research_and_Treatment.md · references/journal_profiles/
• Chest.md · references/journal_profiles/
• Clinical_Cancer_Research.md · references/journal_profiles/
• Clinical_Radiology.md · references/journal_profiles/
• Clinical_and_Molecular_Hepatology.md · references/journal_profiles/
• Diabetes_Metabolism_Journal.md · references/journal_profiles/
• Diagnostic_and_Interventional_Radiology.md · references/journal_profiles/
• ESMO_Open.md · references/journal_profiles/
• Endocrinology_and_Metabolism.md · references/journal_profiles/
• European_Journal_of_Preventive_Cardiology.md · references/journal_profiles/
• European_Radiology.md · references/journal_profiles/
• Hepatology_Communications.md · references/journal_profiles/
• Hepatology_International.md · references/journal_profiles/
• IEEE_TMI.md · references/journal_profiles/
• INSI.md · references/journal_profiles/
• Investigative_Radiology.md · references/journal_profiles/
• JACC_Advances.md · references/journal_profiles/
• JACC_Asia.md · references/journal_profiles/
• JACR.md · references/journal_profiles/
• JAMA.md · references/journal_profiles/
• JAMA_Network_Open.md · references/journal_profiles/
• JAMA_Surgery.md · references/journal_profiles/
• JASN.md · references/journal_profiles/
• JCSM.md · references/journal_profiles/
• JKMS.md · references/journal_profiles/
• JMIR.md · references/journal_profiles/
• JMIR_Medical_Education.md · references/journal_profiles/
• …and 58 more

SKILL.md (first lines)

# Write-Paper Skill

## 8-Phase Pipeline

### Phase 0: Init

Gather essential information from the user before any writing begins.

**Required inputs:**
1. **Title** (working title is fine)
2. **Paper type**: original article, AI validation, case report, case series, meta-analysis, technical note, animal study, NHIS cohort, cross-national
3. **Target journal**: load profile from `${CLAUDE_SKILL_DIR}/references/journal_profiles/`
4. **Research question / hypothesis**
5. **Available data**: what datasets, tables, analyses already exist

**Optional flags:**
- `--no-llm-disclosure`: skip the LLM writing-assistance disclosure. Default is ON.
- `--autonomous`: run Phases 0–7 without user gates (outline approval, T&F plan, discussion planning, section reviews all skipped). Default OFF.

**Actions:**
1. Load the journal profile. If none exists, ask for word limits, abstract format, citation style, figure/table limits, and special requirements.
2. Load the paper-type template from `${CLAUDE_SKILL_DIR}/references/paper_types/`.
3. Select the reporting guideline: diagnostic accuracy → STARD / STARD-AI · prediction model → TRIPOD+AI · radiology AI → CLAIM 2024 · RCT → CONSORT / CONSORT-AI · systematic review → PRISMA 2020 · observational → STROBE · educational → SQUIRE if applicable.
4. **AI/LLM design-stage reporting map** (AI validation, LLM/MLLM, NLP extraction, report generation): map every required AI-reporting item to a manuscript section *before* drafting — model/version/access date, input fields, prompt or fine-tuning protocol, same-backbone zero-shot/few-shot baseline if an adaptation claim is made, test-data independence/contamination, repeatability, and the Methods subsection each will land in. **If any item cannot be placed, halt for design clarification** rather than burying it as a Phase 7 limitation.
5. Create or confirm the project scaffold directory.
6. Record the `--no-llm-disclosure` and `--autonomous` flag states for Phase 1–7 gate logic.
7. **Identify a backbone article** — scan `manuscript/_src/refs.bib` first and propose proactively (ranking: Backbone ranking below); ask only as a fallback. Record the chosen citekey in `project.yaml::backbone_article`. Then gate on its full text — **a backbone whose full text is not extracted is a backbone in name only; the draft would follow an abstract:**

   ```bash
   python3 ${CLAUDE_SKILL_DIR}/scripts/gate_backbone_fulltext.py \
     --project project.yaml --refs manuscript/_src/refs.bib \
     --fulltext-dir pdfs/ --strict
   ```

   A file in `--fulltext-dir` counts as the backbone when it is named `<citekey>.md` or names the backbone DOI/citekey *before* its References heading; a paper that only cites the backbone in its reference list does not count. Known limit: another paper that names the DOI in its own body still resolves — name the file `<citekey>.md` or pass `--fulltext` to remove the doubt.

   `BACKBONE_FULLTEXT_MISSING` / `BACKBONE_FULLTEXT_THIN` → **stop and retrieve it** (`/lit-sync` Phase 2.7, then `/fulltext-retrieval` `pdf_to_md.py`). Do not begin Methods drafting until this passes. If the article is genuinely unavailable in full text, record that limitation and get user confirmation before proceeding on the abstract alone.
8. Summarize the setup — journal constraints, paper type, reporting guideline, backbone article, directory path, LLM-disclosure status — and confirm before proceeding.

#### Phase 0 Gate: Citekey-only references

Citekey discipline turns citation fabrication into a **visible placeholder the submission gate can block**.

1. **Every in-text citation MUST be `[@citekey]`**, with `citekey` present in
   `manuscript/_src/refs.bib`. Pandoc/Quarto style only — no "(Smith et al., 2024)" free text.
2. For a citation intended but not yet imported, use `[@NEW:short-topic]` (kebab-case, ≤30 chars,
   unique in the manuscript).
3. **Never** fabricate a citekey that "looks real" (`[@Smith_2024_AI]`) when the entry is not in
   `refs.bib`. `[@NEW:...]` is the *only* allowed placeholder.
4. All `[@NEW:...]` placeholders must be resolved before Phase 7 (`/search-lit` → `/lit-sync`
   imports verified entries; Better BibTeX refreshes `refs.bib`). Cite only references whose DOI or
   PMID `/search-lit` has confirmed; mark any other as `[UNVERIFIED - NEEDS MANUAL CHECK]`.
5. Pre-submission check — must return zero matches before `/sync-submission` may freeze a package:

   ```bash
   grep -E '\[@NEW:[^]]+\]|\[N\]|\[N–N\]' manuscript/index.qmd
   ```

   Bare `[N]` / `[N–N]` markers mean a manuscript drafted outside this pipeline (no `refs.bib`)
   with method-load-bearing citations left unresolved. Block them exactly like `[@NEW:...]`.

If `refs.bib` is absent, create it empty with the comment
`% refs.bib managed by /lit-sync via Zotero Better BibTeX. Do not hand-edit.`, record
`reference_manager.required_for: project_owner` in `SSOT.yaml`, and proceed — early citations
will all be `[@NEW:...]` until the first `/lit-sync` run.

**Read on demand — once the paper type is known (step 2), and only the row that matches:**

| File | Read it when |
|---|---|
| `references/phase0_init_detail.md` → **Case Report Mode** | paper type is `case report` — word/abstract/reference-limit overrides, the CARE 8-section outline, default figures |
| `references/phase0_init_detail.md` → **Case Series Mode** | paper type is `case series` — the methods-light mini-cohort outline, all-cases summary table, counts-not-rates discipline |
| `references/phase0_init_detail.md` → **Backbone ranking** | `refs.bib` exists and you are proposing a backbone |

---
### Phase 1: Outline

Build the outline on the paper-type template's section structure. Start with a header — working
title, target journal, paper type, total word limit (excluding abstract, references and legends) —
then give every section a word budget and a paragraph- or subsection-level plan, with the budgets
summing within the journal limits. End with the planned tables, figures and supplemental
materials, one line each.

**Gate:** Present the outline to the user. Do NOT proceed until the user approves or requests changes.
**Autonomous mode:** skip this gate; log the outline to `qc/_pipeline_log.md` and proceed to Phase 2.

---

### Phase 2: Tables & Figures

Design all tables and figures BEFORE writing prose, so the narrative serves the data.

1. Review available data with the user. Plan Table 1 (demographics / baseline characteristics — always), Table 2+ (primary and secondary outcomes) and supplemental tables; Figure 1 is the study flow diagram (CONSORT/STARD/PRISMA as applicable), followed by performance curves, forest plots, calibration plots, etc.
2. Call `/analyze-stats` if statistical analysis is needed.
3. Call `/make-figures` with the full figure set the study type requires — do not ask the user to name each figure. **Pass `--study-type`** mapped from the Phase 0 paper type / reporting guideline: diagnostic accuracy → `diagnostic-accuracy`, prediction model → `ai-validation`, systematic review → `meta-analysis`, DTA systematic review → `dta-meta-analysis`, observational → `observational-cohort`, RCT → `rct`, case report → `case-report`.
4. **Visual abstract.** If the journal profile's "Visual Abstract" section requires or encourages one, call `/make-figures` with a visual abstract request: title, Key Points 1 and 3, methodology summary, and the best study figure as the visual element.
5. **Figure embedding.** Scan `analysis/figures/` for every PNG and PDF. For each, insert `![Figure N. Caption](analysis/figures/filename.png){width=80%}` at the appropriate place in Results and draft its legend from the figure type and analysis context.
6. **Manifest verification (HALT gate).** `analysis/figures/_figure_manifest.md` must exist with at least one figure entry — the Phase 7 DOCX build embeds figures from it, and a missing manifest silently drops every figure. If it is missing or empty: in **autonomous mode**, HALT with error code `MANIFEST_MISSING`, log to `qc/_pipeline_log.md`, and write a recovery note to `manuscript/<id>/REPORT.md` Tier-3 section ("rerun /make-figures or manually create _figure_manifest.md"); in **interactive mode**, report the error and ask the user how to proceed.

**Gate:** Present T&F plan to user. Do NOT proceed until user approves.
**Autonomous mode:** skip this gate; log the T&F plan to `qc/_pipeline_log.md` and proceed to Phase 3.

---

### Phase 3: Methods

Write Methods first — it is the most objective section and anchors the rest of the paper.

**Before writing:** Load `${CLAUDE_SKILL_DIR}/references/section_guides/methods.md` and skim the matching study type in `${CLAUDE_SKILL_DIR}/references/exemplar_methods/` (diagnostic-accuracy/STARD, AI-validation/TRIPOD+AI·CLAIM, observational-cohort/STROBE, meta-analysis/PRISMA 2020, RCT/CONSORT 2010): what each paragraph must establish, plus the element that type most often omits. Every exemplar used in Phases 3–6 is synthetic, with placeholder specifics — model its structure; it is not prose to copy.

**Writing order:** (1) Study Design and Setting; (2) Participants / Dataset (inclusion/exclusion, recruitment period); (3) Procedures / Intervention / AI Model description; (4) Outcome Measures (primary and secondary endpoints); (5) Statistical Analysis (`${CLAUDE_SKILL_DIR}/references/section_templates/methods_statistical.md`); (6) Ethics statement; (7) AI/LLM disclosure (unless `--no-llm-disclosure`): when the target journal wants it in Methods, add the Methods paragraph from [LLM Writing Disclosure](#llm-writing-disclosure).

**AI/LLM extraction add-ons (when applicable):**
- In Dataset / Inputs, state exactly which text fields the model received and whether clinical history,
  indication, impression, prior diagnosis, or referral text was masked. If a supplied field can contain
  the target label, Methods must either exclude it or describe a no-leaky-field sensitivity analysis.
- In AI Model or Statistical Analysis, include a same-backbone zero-shot/few-shot comparator when the
  claim is that fine-tuning, LoRA, prompt engineering, or a multi-agent wrapper improves performance.

From Aperivue/medsci-skills, MIT.

More from Aperivue/medsci-skills