# Manuscript Workflow

## Phase 1: Frame the paper

Write `01_topic_brief.md` with:
- working title
- core question
- primary hypothesis
- target population/data source
- design summary
- primary outcome and secondary outcomes
- must-have analyses
- optional extensions
- target manuscript type (`full original article` unless the user explicitly wants a short form)

## Phase 2: Build the evidence map

Use `research-lookup` first, and `literature-review` when the field is broad or inconsistent.

Write `02_evidence_map.md` with four blocks:
1. foundational studies
2. most recent studies
3. conflicting or limiting evidence
4. your study's likely gap statement

For every study you expect to mention in the draft, make sure it can be resolved into a clean BibTeX key for `references.bib`.

## Phase 3: Lock the outline

Use `scientific-writing` only after the gap statement is concrete.

Write `03_outline.md` with:
- title candidates
- abstract skeleton
- IMRAD section bullets
- figure plan
- table plan
- supplementary items
- target word budget for each section
- planned citation-heavy paragraphs in the introduction and discussion

Before moving to prose, confirm that the story can survive as a real paper instead of a short memo.

## Phase 4: Draft the manuscript

Read `manuscript-draft-standards.md` before writing `04_manuscript_draft.md`.

Write `04_manuscript_draft.md` in full paragraphs.

Recommended order:
1. Introduction
2. Methods
3. Results
4. Discussion
5. Abstract last

Default output standard:
- aim for a full original-article draft, not a 1-2k word summary
- keep section lengths within the recommended bands in `manuscript-draft-standards.md`
- use inline citations linked to `references.bib`, preferably Pandoc cite syntax such as `[@Chen_2024]`
- when writing narrative citations, keep the key visible: `Chen et al. [@Chen_2024]`
- introduction and discussion paragraphs that summarize prior work should almost never be citation-free
- methods should cite external cohorts, harmonization approaches, or analytic conventions when those are described as inherited rather than newly invented
- results paragraphs describing your own package outputs usually do not need literature citations unless they explicitly compare against prior studies

## Phase 5: Capture unresolved issues

Write `05_revision_notes.md` with:
- unsupported claims to trim
- analyses still needed
- missing citations
- reviewer-facing weaknesses
- decisions deferred to coauthors
- any sections that are still shorter than target and need substantive expansion

## Optional branch points

- Pull `citation-management` when citations are incomplete or messy.
- Pull a method-specific validation skill when external validation or MR feasibility is uncertain.
- Pull `research-audit` before final handoff.
