paper-writing

name: paper-writing description: End-to-end manuscript writing pipeline from outline to assembled draft

Purpose

Orchestrate end-to-end manuscript drafting from outline to assembled manuscript across four phases with interactive approval gates.

Inputs

outline_file
findings_file
existing_manuscript_file
revision_brief_file
review_comment_map_file

Outputs

paper_session.yaml
manuscript_outline.md
short_draft_{section}.md
draft_{section}.md
manuscript_draft.md
references.bib
draft_issues.md
revision_trace.md

Required Policies

citation-verification
theory-claims-discipline

Profile Keys Read

method.family
method.subtype
journal.name
journal.intro_structure
journal.discussion_expectations
writing.tone

Constraints

NEVER hallucinate citations in full drafts - sub-agents must use only citations present in the approved short draft and outline
NEVER call zotero_get_item_fulltext or fetch during any phase - metadata only
Use native Task tool for parallel sub-agent dispatch - do not rely on third-party orchestration plugins
Always check for paper_session.yaml at startup and resume from last completed phase if found
Each sub-agent in Phase 3 receives only its own section context (short draft + outline + profile) - not the full session context
In revision mode, preserve valid existing prose unless the revision brief, consistency checks, or explicit user instructions require change
In revision mode, do not silently ignore high-priority items from the revision brief or review comment map

Process Steps

At startup: check for paper_session.yaml; if found, resume from last completed phase
Determine draft_mode: use new if starting from outline_file only; use revision if revision_brief_file and existing_manuscript_file are provided
Read active profile overlays from config/active.yaml
Load journal section structure and method-family rigor checks
Phase 1 new mode: Read outline_file and produce manuscript_outline.md with section purposes, argument skeleton, word count targets, and citation placeholders; if findings_file provided, annotate Results/Discussion hooks
Phase 1 revision mode: Read existing_manuscript_file, shard the baseline manuscript by section, read revision_brief_file and optional review_comment_map_file, then produce manuscript_outline.md showing keep/revise/cut/add actions, linked comment IDs, and revised word count targets
Phase 1: STOP - present outline to user and request approval or changes; do not proceed until approved
Phase 1 complete: write paper_session.yaml with phase=1, approved_outline=true, draft_mode, and section statuses=pending; in revision mode also store baseline_manuscript and revision_brief references
Phase 2 new mode: For each section in order - present 2-3 sentence summary of planned argument; ask one focused clarification question; incorporate response; produce short draft (300-500 words) with claims, transitions, citation placeholders; mark section status=short_draft in paper_session.yaml
Phase 2 revision mode: For each section in order - summarize what stays from the baseline section and what must change from the revision brief; ask one focused clarification question only when revision strategy is ambiguous; produce a revision short draft (300-500 words) that preserves the retained argument spine, marks required additions or cuts, and links reviewer issue IDs; mark section status=short_draft in paper_session.yaml
Phase 2: After all short drafts produced, STOP - present all short drafts for user review; do not proceed until approved
Phase 2 complete: update paper_session.yaml with phase=2, all sections=approved
Phase 3 new mode: Dispatch parallel Task tool calls (one per section) in a single message; each Task receives: section name, its short draft, manuscript_outline.md, and active profile; each Task applies journal-manuscript-writing skill and rigor policies; each Task saves output to draft_{section}.md
Phase 3 revision mode: Dispatch parallel Task tool calls (one per section) in a single message; each Task receives: section name, baseline section text, its revision short draft, manuscript_outline.md, linked reviewer issue IDs, and active profile; each Task revises or rewrites only as needed and saves output to draft_{section}.md
Phase 3: Collect Task completions; report any failed section; update paper_session.yaml with phase=3
Phase 4: Merge all draft_{section}.md files into manuscript_draft.md in journal section order
Phase 4: Cross-section consistency checks - verify construct names are consistent throughout; verify contribution claims in intro match discussion implications; verify all in-text citations exist in references.bib
Phase 4: Repetition detection - scan all sections for near-duplicate sentences (same claim, same or closely paraphrased wording appearing in 2+ sections); flag high-risk zones: intro contribution summary vs discussion theoretical contribution, methodology overview vs study design, limitations in Discussion vs Conclusion
Phase 4: Run check-refs skill on manuscript_draft.md to validate all references against Zotero
Phase 4: Write draft_issues.md with all flagged inconsistencies, repetitions, and reference gaps; each issue includes section location and severity
Phase 4 revision mode: Write revision_trace.md mapping reviewer issue IDs to manuscript changes, rebuttal-only handling, deferrals, or declines
Phase 4 complete: update paper_session.yaml with phase=complete

Failure Handling

If outline_file is missing or unreadable, request valid path and pause
If revision mode is requested without both existing_manuscript_file and revision_brief_file, request the missing file and pause
If paper_session.yaml exists but is corrupt, warn user and offer to restart from Phase 1
If a Phase 3 sub-agent Task fails for a section, mark that section as failed in paper_session.yaml and continue other sections; report failure at end
If no short drafts are approved after Phase 2, do not proceed to Phase 3
If assembly fails because a draft_{section}.md is missing, list missing sections and pause