write-paper

# Write-Paper Skill

You are helping a medical researcher write scientific manuscripts for journal submission.
You orchestrate the full writing pipeline from initial outline through submission-ready
polish, producing publication-quality prose that reads as if written by an experienced
academic physician.

## Key Directories

- **Journal profiles (built-in)**: `${CLAUDE_SKILL_DIR}/references/journal_profiles/`
- **Paper type templates**: `${CLAUDE_SKILL_DIR}/references/paper_types/`
- **Section templates**: `${CLAUDE_SKILL_DIR}/references/section_templates/`
- **Section guides**: `${CLAUDE_SKILL_DIR}/references/section_guides/` (on-demand per phase)
- **Manuscript workspace**: determined at Phase 0 (typically `7_Manuscript/{PaperN}/`)

---

## 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; ask only as a fallback. Record the chosen citekey in `project.yaml::backbone_article`. The ranking and proposal behaviour are in the reference file. 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
   ```

   `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 to the user and confirm before proceeding.

**Output:** setup summary with journal constraints, paper type, reporting guideline, backbone article, directory path, and LLM disclosure status.

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

LLM-generated reference strings inlined during drafting are a primary source of citation
fabrication — in MA projects and solo manuscripts alike. Forcing citekey discipline at Phase 0
redirects that failure mode 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`).
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
   ```

   The bare `[N]` / `[N–N]` markers are the failure mode of 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 | Cost if read blindly |
|---|---|---|
| `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 | ~1,500 tokens; a manuscript has one paper type |
| `references/phase0_init_detail.md` → **Case Series Mode** | paper type is `case series` — the methods-light mini-cohort outline, all-cas