paper-writing

Workflow 3: 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 → /paper-write → /paper-compile → /auto-paper-improvement-loop
  (outline)     (plots)        (LaTeX)        (build PDF)       (review & polish ×2)

Each phase builds on the previous one's output. The final deliverable is a polished, reviewed paper/ directory with LaTeX source and compiled PDF.

In this hybrid pack, the pipeline itself is unchanged, but paper-plan and paper-write use Orchestra-adapted shared references for stronger story framing and prose guidance.

Constants

• VENUE = ICLR — Target venue. Options: ICLR, NeurIPS, ICML, CVPR, ACL, AAAI, ACM, IEEE_JOURNAL (IEEE Transactions / Letters), IEEE_CONF (IEEE conferences). Affects style file, page limit, citation format.
• MAX_IMPROVEMENT_ROUNDS = 2 — Number of review→fix→recompile rounds in the improvement loop.
• REVIEWER_MODEL = gpt-5.5 — Model used via Codex MCP for plan review, figure review, writing review, and improvement 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 improvement loop (Phase 5) 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 /auto-paper-improvement-loop.
• ILLUSTRATION = figurespec — Architecture/illustration generator for Phase 2b: figurespec (default, deterministic JSON→SVG via /figure-spec, best for architecture/workflow/topology), gemini (AI-generated via /paper-illustration, best for qualitative method illustrations; needs GEMINI_API_KEY), mermaid (Mermaid syntax via /mermaid-diagram, free, best for flowcharts), or false (skip Phase 2b, manual only).

Override inline: /paper-writing "NARRATIVE_REPORT.md" — venue: NeurIPS, illustration: gemini, human checkpoint: true

IEEE example: /paper-writing "NARRATIVE_REPORT.md" — venue: IEEE_JOURNAL

Inputs

This pipeline accepts one of:

1. NARRATIVE_REPORT.md (best) — structured research narrative with claims, experiments, results, figures
2. Research direction + experiment results — the skill will help draft the narrative first
3. Existing PAPER_PLAN.md — skip Phase 1, start from Phase 2

The more detailed the input (especially figure descriptions and quantitative results), the better the output.

Pipeline

Phase 0: Assurance Setup

Resolve the active assurance level and persist it so Phase 6's external verifier reads the same value. Run once at pipeline start, before Phase 1.

Resolution order (first match wins):

1. Explicit — assurance: draft | submission in $ARGUMENTS
2. Derived from — effort:
3. lite / balanced → draft (default, zero change from current behavior)
4. max / beast → submission
5. Default: draft

Action:

mkdir -p paper/.aris
echo "<resolved-level>" > paper/.aris/assurance.txt   # draft or submission

What each level does downstream:

• draft — Existing behavior. Audits run only when their content detector

matches (Phase 4.5 / 4.7 / 5.5 / 5.8). Missing artifacts are non-blocking. Silent-skip allowed.

• submission — The three mandatory audits (proof-checker,

paper-claim-audit, citation-audit) are treated as load-bearing gates. Each sub-audit must emit its JSON artifact (PASS / WARN / FAIL / NOT_APPLICABLE / BLOCKED / ERROR) — never silent-skip. Phase 6 runs verify_paper_audits.sh (canonical name; resolved per shared-references/integration-contract.md §2); a non-zero exit blocks the Final Report.

Escape hatch: a user wanting the old "beast = depth-only, no audit gate" can pass — effort: beast, assurance: draft explicitly. Legal but discouraged for actual submissions. See shared-references/assurance-contract.md for the full contract.

Announce the resolved level in-line before Phase 1:

📋 Assurance: <level> (derived from effort: <effort>)
   <either "current behavior, no audit gate" OR "mandatory audits gated by verify_paper_audits.sh (resolved per integration-contract §2)">

Phase 1: Paper Plan

Invoke /paper-plan to create the structural outline:

/paper-plan "$ARGUMENTS"

What this does:

• Parse NARRATIVE_REPORT.md for claims, evidence, and figure descriptions
• Build a Claims-Evidence Matrix — every claim maps to evidence, every experiment supports a claim
• Design section structure (5-8 sections depending on paper type)
• Plan figure/table placement with data sources
• Scaffold citation structure
• GPT-5.4 reviews the plan for completeness

Output: PAPER_PLAN.md with section plan, figure plan, citation scaffolding.

Checkpoint: Present the plan summary to the user.

📐 Paper plan complete:
- Title: [proposed title]
- Sections: [N] ([list])
- Figures: [N] auto-generated + [M] manual
- Target: [VENUE], [PAGE_LIMIT] pages

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 to generate data-driven plots and tables:

/paper-figure "PAPER_PLAN.md"

What this does:

• Read figure plan from PAPER_PLAN.md
• Generate matplotlib/seaborn plots from JSON/CSV data
• Generate LaTeX comparison tables
• Create figures/latex_includes.tex for easy insertion
• GPT-5.4 reviews figure quality and captions

Output: figures/ directory with PDFs, generation scripts, and LaTeX snippets.

Scope: paper-figure covers data plots and comparison tables. Architecture diagrams, pipeline figures, and method illustrations are handled in Phase 2b below.

Phase 2b: Architecture & Illustration Generation

Skip this step entirely if illustration: false.

If the paper plan includes architecture diagrams, pipeline figures, audit cascades, or method illustrations, invoke the appropriate generator based on the illustration parameter:

When illustration: figurespec (default) — invoke /figure-spec:

/figure-spec "[architecture/workflow description from PAPER_PLAN.md]"

• Deterministic JSON → SVG vector rendering (editable, reproducible)
• Best for: system architecture, workflow pipelines, audit cascades, layered topology
• Output: figures/.svg + figures/.pdf (via rsvg-convert) + figures/specs/*.json
• No external API, runs fully local

When illustration: gemini — invoke /paper-illustration:

/paper-illustration "[method description from PAPER_PLAN.md or NARRATIVE_REPORT.md]"

• Claude plans → Gemini optimizes → Nano Banana Pro renders → Claude reviews (score ≥ 9)
• Best for: qualitative method illustrations, natural-style diagrams, result grids
• Output: figures/ai_generated/*.png
• Requires GEMINI_API_KEY environment variable

When illustration: mermaid — invoke /mermaid-diagram:

/mermaid-diagram "[method description from PAPER_PLAN.md]"

• Generates Mermaid syntax diagrams (flowchart, sequence, class, state, etc.)
• Best for: lightweight flowcharts, state machines, simple sequence diagrams
• Output: figures/.mmd + figures/.png
• Free, no API key needed

When illustration: false — skip entirely. All non-data figures must be created manually (draw.io, Figma, TikZ) and placed in figures/ before Phase 3.

Choosing the right mode:

• Formal architecture / workflow / topology figures → figurespec (default)
• Method concept illustrations with natural style → gemini
• Quick flowchart / state machine → mermaid
• Full manual control → false

These are complementary, not mutually exclusive: you can run multiple generators for different figures in