paper-writing-pipeline

name: paper-writing-pipeline description: "Full paper writing pipeline. Orchestrates paper-plan → paper-figure-generate → paper-draft → paper-review-loop → paper-covert to go from upstream research artifacts to a polished, submission-ready manuscript package (Markdown → LaTeX → PDF + DOCX). Use when user says "write paper pipeline", "paper writing", or wants the complete paper generation workflow." argument-hint: [narrative-report-path-or-topic] allowed-tools: Bash(*), Read, Write, Edit, Grep, Glob, Agent, Skill, mcp__codex__codex, mcp__codex__codex-reply

Paper Writing Pipeline

Orchestrate a complete paper writing workflow for: $ARGUMENTS

Overview

This skill chains five sub-skills into a single automated pipeline:

/paper-plan → /paper-figure-generate → /paper-draft → /paper-review-loop → /paper-covert
  (outline)       (figures & prompts)     (Markdown)     (review & revise)    (LaTeX + PDF + DOCX)

Each phase builds on the previous one's output. The pipeline takes upstream research artifacts and produces a polished, reviewed submission package in output/submission/.

Artifact Flow

Upstream artifacts (RESEARCH_PLAN, LIT_REVIEW, IDEA_REPORT, FINAL_PROPOSAL,
                    EXPERIMENT_PLAN, EXPERIMENT_RESULT, NARRATIVE_REPORT)
    ↓ Phase 1: paper-plan
output/PAPER_PLAN.md  (§0–§26: outline, claims matrix, figure plan, citations)
    ↓ Phase 2: paper-figure-generate
output/figures/       (PNGs, PDFs, scripts, prompts, FIGURE_MANIFEST.md, FIGURE_CAPTIONS.md)
    ↓ Phase 3: paper-draft
output/manuscript/    (MANUSCRIPT_DRAFT.md, sections/*.md, CLAIM_SUPPORT_MAP.md, COVERAGE_GAPS.md)
    ↓ Phase 4: paper-review-loop
output/manuscript/    (MANUSCRIPT_REVISED.md, sections_revised/*.md, REVIEW_REPORT.md, CLAIM_RISK_REPORT.md)
    ↓ Phase 5: paper-covert
output/submission/    (latex/, pdf/MANUSCRIPT_SUBMISSION_READY.pdf, docx/, SUBMISSION_MANIFEST.md)

Constants

• TARGET_VENUE = IJGIS — Target venue. Supported: TGIS, RSE, ISPRS_JPRS, AAG_ANNALS, IEEE_TGRS, ICLR, NeurIPS, ICML, CVPR, ACL, AAAI, ACM, IEEE_JOURNAL (IEEE Transactions / Letters), IEEE_CONF (IEEE conferences). Affects template selection, page limit, citation format, and section structure.
• MAX_REVIEW_ROUNDS = 2 — Number of review→revise rounds in the review loop (Phase 4).
• REVIEWER_MODEL = gpt-5.4 — Model used via Codex MCP for plan review, figure review, draft review, and review loop.
• AUTO_PROCEED = true — Auto-continue between phases. Set false to pause and wait for user approval after each phase.
• HUMAN_CHECKPOINT = false — When true, the review loop (Phase 4) pauses after each round's review to let you see the score and provide custom modification instructions. When false (default), the loop runs fully autonomously. Passed through to paper-review-loop.
• DRAFT_MODE — One of full, partial, skeleton. Determined automatically by paper-draft based on evidence readiness. Can be forced via argument.

Override inline: /paper-writing-pipeline "NARRATIVE_REPORT.md" — venue: NeurIPS, human checkpoint: true IEEE example: /paper-writing-pipeline "NARRATIVE_REPORT.md" — venue: IEEE_JOURNAL

Inputs

This pipeline accepts one of:

1. output/NARRATIVE_REPORT.md (best) — structured research narrative with claims, experiments, results, figure plans, verified citations. Produced by generate-report.
2. Upstream research artifacts — the pipeline's paper-plan phase will read all available artifacts (RESEARCH_PLAN.md, output/LIT_REVIEW_REPORT.md, output/IDEA_REPORT.md, output/refine-logs/FINAL_PROPOSAL.md, output/EXPERIMENT_PLAN.md, output/EXPERIMENT_RESULT.md, output/NARRATIVE_REPORT.md) and build the plan from whatever exists.
3. Existing output/PAPER_PLAN.md — skip Phase 1, start from Phase 2.
4. Existing output/manuscript/MANUSCRIPT_DRAFT.md — skip Phases 1–3, start from Phase 4 (review loop).
5. Existing output/manuscript/MANUSCRIPT_REVISED.md — skip Phases 1–4, start from Phase 5 (conversion).

The more detailed the input (especially figure descriptions, quantitative results, and verified claims in memory/APPROVED_CLAIMS.md), the better the output.

Skip Logic

Before starting, check which artifacts already exist to determine the entry point:

When resuming, always read handoff.json first — it records the last completed phase and any pending issues.

Pipeline

Phase 1: Paper Plan

Invoke paper-plan to create the structural outline:

Skill: paper-plan "$ARGUMENTS"

What this does:

• Reads all available upstream artifacts (RESEARCH_PLAN, LIT_REVIEW_REPORT, IDEA_REPORT, FINAL_PROPOSAL, EXPERIMENT_PLAN, EXPERIMENT_RESULT, NARRATIVE_REPORT) — each is optional
• Determines venue and paper type from arguments, RESEARCH_PLAN, or defaults
• Loads venue-specific template from templates/
• Builds the full §0–§26 plan per templates/PAPER_PLAN_TEMPLATE.md:
  • One-paragraph summary and one-sentence claim
  • Target journal strategy and audience
  • Research gap and contributions (with "not claiming" boundary)
  • Research questions and hypotheses
  • Data and methodological plan
  • Experiment inventory and results summary
  • Claims-Evidence Matrix (§12) — the backbone mapping every claim to evidence
  • Figure & Table Plan (§13–§14) — with hero figure detail
  • Related work synthesis in themed clusters
  • Discussion, limitations, and future work plan
  • Abstract blueprint and title options
  • Writing instructions for the downstream draft agent
  • Readiness assessment and executive summary
• Scaffolds citation structure from verified sources
• REVIEWER_MODEL reviews the plan for completeness (8 scoring dimensions)
• Runs self-check (10 verification items) before finalizing

Output: output/PAPER_PLAN.md with the full §0–§26 structure.

Checkpoint: Present the plan summary to the user.

Paper plan complete:
- Title: [proposed title]
- Venue: [VENUE] | Page limit: [MAX_PAGES]
- Sections: [N] ([list])
- Contributions: [N]
- Claims in evidence matrix: [M] (supported: X, pending: Y)
- Figures planned: [total] (hero: 1, auto: X, manual: Y)
- Missing inputs: [list or "none"]
- Readiness: [full / partial / skeleton]

Shall I proceed with figure generation?

• User approves (or AUTO_PROCEED=true) → proceed to Phase 2.
• User requests changes → adjust plan and re-present.

Phase 2: Figure Generation

Invoke paper-figure-generate to produce publication-quality figures:

Skill: paper-figure-generate "all"

What this does:

• Reads the Figure Plan (§13) and Table Plan (§14) from output/PAPER_PLAN.md
• Classifies each figure into a code pathway (reproducible plots, maps, charts) or prompt pathway (architecture diagrams, workflow schematics, conceptual figures)
• For code figures: writes Python scripts to output/figures/scripts/, generates PNGs + PDFs at 300 DPI, applies venue-appropriate styling (colorblind-safe palette, print-legible fonts, proper map elements)
• For prompt figures: writes detailed structured prompts to output/figures/prompts/ with element inventories, style constraints, and negative prompts — ready to paste into an external image model
• Creates specification stubs for figures whose data is missing
• Writes manuscript-ready captions to output/figures/FIGURE_CAPTIONS.md
• Maintains output/figures/FIGURE_MANIFEST.md with status tracking per figure
• Runs a consistency pass across all figures (numbering, palette, terminology)
• REVIEWER_MODEL optionally reviews figure quality and captions

Output: output/figures/ directory with rendered figures, scripts, prompts, manifest, and captions.

Scope: Code pathway auto-generates data-driven figures (plots, maps, comparison tables). Prompt pathway produces ready-to-paste prompts for architecture diagrams, workflow figures, and graphical abstracts. The user supplies rendered prompt-pathway images before proceeding.

Checkpoint: List generated vs. manual figures.

Figures complete:
- Code-generated: [list with status]
- Prompt-generated: [list — prompts ready, renders needed from user]
- Stubs (data missing): [list with blockers]
- Manifest: output/figures/FIGURE_MANIFEST.md
- Captions: output/figures/FIGURE_CAPTIONS.md

[If prompt figures need renders]: Please generate images from prompts in output/figures/prompts/ and place renders in output/figures/ before I proceed.
[If all code figures ready]: Shall I proceed with manuscript drafting?

• User provides renders / approves (or AUTO_PROCEED=true) → proceed to Phase 3.
• User requests changes → adjust figures and re-present.

Phase 3: Manuscript Drafting

Invoke paper-draft to generate the Markdown manuscript:

Skill: paper-draft "all"

What this does:

• Reads output/PAPER_PLAN.md (§0–§26) as the manuscript intent
• Determines DRAFT_MODE (full / partial / skeleton) from plan §25 readiness assessment
• Consults evidence files: memory/APPROVED_CLAIMS.md, output/LIT_REVIEW_REPORT.md, output/EXPERIMENT_RESULT.md, output/figures/FIGURE_MANIFEST.md
• Selects section structure based on venue and paper type (5–8 sections, flexible)
• Drafts each section following venue-specific academic prose conventions:
  • Introduction with numbered contributions
  • Related work in themed clusters (not a paper list)
  • Methods with spatial/GIScience rigor
  • Results led by strongest approved claim
  • Discussion closing the loop to the gap
  • Limitations mirroring plan §17
• Produces companion artifacts:
  • CLAIM_SUPPORT_MAP.md — every claim traced to evidence
  • COVERAGE_GAPS.md — missing experiments, figures, citations
  • CITATION_GAPS.md — claims needing citations
  • REVISION_NOTES.md — items for next pass
• Runs consistency checks (terminology, figure references, contribution closure)
• REVIEWER_MODEL optionally reviews each section
• Never fabricates results, citations, or figures — uses [PLACEHOLDER] and [CITE: topic] markers

Output: output/manuscript/ directory with MANUSCRIPT_DRAFT.md, sections/*.md, and companion artifacts.

Checkpoint: Report draft completion.

Manuscript draft complete:
- Mode: [full / partial / skeleton]
- Venue: [TARGET_VENUE]
- Sections: [N] written ([list])
- Word count: [total] (budget: [limit])
- Claims supported: [X] / [total] in evidence matrix
- Coverage gaps: [K] (see output/manuscript/COVERAGE_GAPS.md)
- Citation gaps: [J] (see output/manuscript/CITATION_GAPS.md)

Shall I proceed with the review loop?

• User approves (or AUTO_PROCEED=true) → proceed to Phase 4.
• User requests changes → revise specific sections.

Phase 4: Review and Revision Loop

Invoke paper-review-loop to critically review and revise the manuscript:

Skill: paper-review-loop "all"

What this does (up to MAX_REVIEW_ROUNDS rounds):

Each round follows this sequence:

1. Cold-read evaluation — REVIEWER_MODEL (gpt-5.4 xhigh) reviews the manuscript as a demanding journal reviewer, scoring 8 dimensions:
   • Gap clarity, novelty precision, methods rigor, results discipline
   • Discussion depth, literature positioning, journal fit, language flow
2. Claim risk audit — Cross-checks every claim against CLAIM_SUPPORT_MAP.md and APPROVED_CLAIMS.md; flags overclaims
3. Issue classification — Major (structural, argument, evidence) → Moderate (transitions, terminology) → Minor (polish)
4. Human checkpoint (if HUMAN_CHECKPOINT=true) — Present scores and top issues; wait for user guidance
5. Revision — Implements fixes ordered by severity (majors first); writes to sections_revised/*.md and MANUSCRIPT_REVISED.md
6. Verification — Checks claim closure, limitation closure, figure closure, contribution closure, terminology consistency

Key artifacts produced:

• MANUSCRIPT_REVISED.md — the revised manuscript (basis for next round or conversion)
• REVIEW_REPORT.md — structured reviewer report with per-dimension scores and verdict
• MAJOR_ISSUES.md / MINOR_ISSUES.md — ranked issue lists with resolution status
• CLAIM_RISK_REPORT.md — claim-wording-vs-evidence audit
• JOURNAL_FIT_NOTES.md — venue-specific alignment assessment
• REVISION_LOG.md — what changed and why, keyed to issue IDs
• REVIEW_LOOP_STATE.json — round counter, scores, unresolved issues (for resume)

Generator-evaluator separation enforced: REVIEWER_MODEL evaluates; Claude Code revises. The reviewer never sees the revision context; the reviser never self-scores. ThreadId persistence ensures reviewer continuity across rounds.

Output: Updated output/manuscript/ with revised manuscript, review artifacts, and loop state.

Checkpoint: Report review results.

Review loop complete (Round [N]):
- Verdict: [ready / almost / not ready] for [TARGET_VENUE]
- Scores: gap=[X] novelty=[X] methods=[X] results=[X] discussion=[X] lit=[X] fit=[X] language=[X]
- Major issues: [resolved] / [total]
- Unresolved: [list of carry-over issues, if any]

Shall I proceed with LaTeX conversion and PDF generation?

• User approves (or AUTO_PROCEED=true) → proceed to Phase 5.
• User requests additional rounds → run another review-revise cycle.
• User requests specific fixes → apply targeted revisions.

Phase 5: Conversion and Submission Package

Invoke paper-covert to convert the final manuscript into a submission package:

Skill: paper-covert "$VENUE"

What this does:

• Reads the best available manuscript: MANUSCRIPT_REVISED.md (preferred) → MANUSCRIPT_DRAFT.md (fallback)
• Resolves venue from argument → PAPER_PLAN.md → default; loads venue profile from profiles/<venue>.yaml
• Builds modular LaTeX tree in output/submission/latex/:
  • main.tex (lean entry with \input only)
  • preamble.tex (venue-specific packages and environments)
  • metadata.tex (title, keywords, highlights)
  • sections/*.tex (one per manuscript section, Markdown → LaTeX conversion)
  • references.bib (from existing .bib or synthesized from paper-cache; never fabricated)
  • figures/ (copied from output/figures/ per FIGURE_MANIFEST)
  • build.sh (latexmk → pdflatex fallback build script)
• Compiles PDF via latexmk -pdf with auto-fix for common errors
• Exports DOCX via Pandoc (LaTeX source preferred, Markdown fallback)
• Writes SUBMISSION_MANIFEST.md with:
  • Source manuscript path and readiness level
  • Files generated with paths
  • Bibliography gaps (unresolved citations)
  • Asset gaps (missing figures)
  • Content gaps (remaining [PLACEHOLDER] blocks)
  • Build status (PDF pass/fail, DOCX pass/fail)
  • Honest readiness assessment — never marks "submission-ready" with open gaps

Output: output/submission/ with LaTeX source, PDF, DOCX, and manifest.

Does NOT:

• Rewrite or restructure prose (that was Phase 4)
• Invent citations or bibliographic entries
• Reference figures not in FIGURE_MANIFEST.md
• Modify output/manuscript/ (read-only)

Phase 6: Final Report

After all phases complete, present a summary report:

# Paper Writing Pipeline Report

**Input**: [source artifacts used]
**Venue**: [TARGET_VENUE]
**Date**: [today]

## Pipeline Summary

| Phase | Status | Output |
|-------|--------|--------|
| 1. Paper Plan | [status] | output/PAPER_PLAN.md |
| 2. Figures | [status] | output/figures/ ([N] code + [M] prompt + [K] stubs) |
| 3. Manuscript Draft | [status] | output/manuscript/MANUSCRIPT_DRAFT.md ([mode], [words] words) |
| 4. Review Loop | [status] | output/manuscript/MANUSCRIPT_REVISED.md (Round [N], verdict: [X]) |
| 5. Conversion | [status] | output/submission/ (PDF: [ok/fail], DOCX: [ok/fail]) |

## Review Scores (Final Round)
| Dimension | Score |
|-----------|-------|
| Gap clarity | [X]/10 |
| Novelty precision | [X]/10 |
| Methods rigor | [X]/10 |
| Results discipline | [X]/10 |
| Discussion depth | [X]/10 |
| Literature positioning | [X]/10 |
| Journal fit | [X]/10 |
| Language flow | [X]/10 |

## Deliverables
- output/PAPER_PLAN.md — Manuscript plan (§0–§26)
- output/figures/ — Figures, scripts, prompts, manifest, captions
- output/manuscript/MANUSCRIPT_DRAFT.md — Initial Markdown draft
- output/manuscript/MANUSCRIPT_REVISED.md — Reviewed and revised draft
- output/manuscript/CLAIM_SUPPORT_MAP.md — Claim-to-evidence traceability
- output/manuscript/REVIEW_REPORT.md — Structured review report
- output/submission/latex/ — Modular LaTeX source
- output/submission/pdf/MANUSCRIPT_SUBMISSION_READY.pdf — Compiled PDF
- output/submission/docx/MANUSCRIPT_SUBMISSION_READY.docx — Word document
- output/submission/SUBMISSION_MANIFEST.md — Package manifest with readiness assessment

## Open Issues (if any)
- [unresolved major issues from MAJOR_ISSUES.md]
- [bibliography gaps from CITATION_GAPS.md]
- [asset gaps from SUBMISSION_MANIFEST.md]
- [content gaps — remaining [PLACEHOLDER] blocks]

## Next Steps
- [ ] Visual inspection of PDF
- [ ] Generate renders for prompt-pathway figures (if pending)
- [ ] Resolve any remaining [PLACEHOLDER] blocks
- [ ] Add author information
- [ ] Final venue compliance check (/submit-check)
- [ ] Submit to [venue]

Key Rules

• Large file handling: If the Write tool fails due to file size, immediately retry using Bash (cat << 'EOF' > file) to write in chunks. Do NOT ask the user for permission — just do it silently.
• Don't skip phases. Each phase builds on the previous one — skipping leads to missing artifacts that downstream phases expect.
• Checkpoint between phases when AUTO_PROCEED=false. Present results and wait for approval.
• Prompt-pathway figures require user renders. If the paper needs architecture diagrams or conceptual figures produced via image models, the user must provide the rendered images before Phase 3. The pipeline generates the prompts; the user generates the images.
• Evidence integrity throughout. The pipeline never fabricates results, citations, or figures at any phase. Missing evidence produces marked placeholders, not inventions.
• Generator-evaluator separation. Maintained across the entire pipeline: paper-draft writes, paper-review-loop evaluates and revises, paper-covert converts. No skill self-scores its own output.
• Preserve all intermediate artifacts. The user needs the full trail: plan → figures → draft → reviewed → revised → submission package.
• Document everything. The final report should be self-contained. Each phase produces its own artifacts (manifests, gap reports, state files).
• Respect page limits. If the paper exceeds the venue limit, suggest specific cuts during Phase 4 (review loop) rather than silently truncating during Phase 5 (conversion).
• Venue consistency. TARGET_VENUE propagates through all 5 phases via output/PAPER_PLAN.md. Do not change venue mid-pipeline without re-running from Phase 1.

Error Handling

Composing with Other Workflows

/idea-discovery-pipeline "direction"     ← Workflow 1: find and refine ideas
/deploy-experiment                       ← Execute experiments
/auto-review-loop "research topic"       ← Adversarial review of research quality
/generate-report                         ← Consolidate into NARRATIVE_REPORT.md
/paper-writing-pipeline "NARRATIVE_REPORT.md"  ← You are here: manuscript to submission
                                              submit!

Or use /full-pipeline for the end-to-end flow (idea discovery → experiments → review → report), then /paper-writing-pipeline for the manuscript production.

Sub-Skill Reference