paper-writing skill

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, IEEEJOURNAL (IEEE Transactions / Letters), IEEECONF (IEEE conferences). Affects style file, page limit, citation format.
• MAXIMPROVEMENTROUNDS = 2 — Number of review→fix→recompile rounds in the improvement loop.
• REVIEWERMODEL = gpt-6-astra** — Model used via Codex MCP for plan review, figure review, writing review, and improvement loop.
• AUTOPROCEED = true** — Auto-continue between phases. Set false to pause and wait for user approval after each phase.
• HUMANCHECKPOINT = 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 GEMINIAPIKEY), codex-image2 (AI-generated via /paper-illustration-image2 through the local Codex native image bridge — no external API key, uses your ChatGPT Plus/Pro quota; experimental), 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 "NARRATIVEREPORT.md" — venue: IEEEJOURNAL

Inputs

This pipeline accepts one of:

1. NARRATIVEREPORT.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 PAPERPLAN.md — skip Phase 1, start from Phase 1.5** (the contract negotiation still runs; only resuming a genuine pre-1.5 legacy run may skip it, and then Phase 6.0's row 0 records "no contract")

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

Optional: Style reference (— style-ref: , opt-in)

Lets the user steer structural style (section ordering, theorem density, sentence cadence, figure density, bibliography style) of the generated paper toward a reference paper they admire. Default OFF — when the user does not pass — style-ref, do nothing differently from before.

When — style-ref: is in $ARGUMENTS, run the helper FIRST, before Phase 1 (paper-plan):

# Resolve $STYLE_HELPER via the canonical strict-safe chain (see
# shared-references/integration-contract.md §2). Policy A — gate:
# unresolved helper means --style-ref cannot be satisfied, so abort.
cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills.txt ]; then
    ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null) || true
fi
if [ -z "${ARIS_REPO:-}" ] && [ -f "$HOME/.aris/repo" ]; then
    ARIS_REPO=$(cat "$HOME/.aris/repo" 2>/dev/null) || true
fi
STYLE_HELPER=".aris/tools/extract_paper_style.py"
[ -f "$STYLE_HELPER" ] || STYLE_HELPER="tools/extract_paper_style.py"
[ -f "$STYLE_HELPER" ] || { [ -n "${ARIS_REPO:-}" ] && STYLE_HELPER="$ARIS_REPO/tools/extract_paper_style.py"; }
[ -f "$STYLE_HELPER" ] || {
  echo "ERROR: extract_paper_style.py not resolved at .aris/tools/, tools/, \$ARIS_REPO/tools/, or via ~/.aris/repo." >&2
  echo "       Fix: rerun bash tools/install_aris.sh or smart_update.sh (refreshes ~/.aris/repo), export ARIS_REPO, or copy the helper to tools/." >&2
  echo "       --style-ref cannot be satisfied; aborting." >&2
  exit 1
}
STYLE_STATUS=0
CAC

Then forward — style-ref: only to the writer-side sub-skills:

• /paper-plan (Phase 1) — outline structure
• /paper-write (Phase 3) — section-by-section prose
• /paper-illustration (Phase 2b) — figure structural matching, optional

Sources accepted: local TeX dir / file, local PDF, arXiv id, http(s) URL. Overleaf URLs/IDs are rejected — clone via /overleaf-sync setup first and pass the local clone path.

Strict rules (full contract in tools/extractpaperstyle.py docstring):

• Use styleprofile.md as structural** guidance only. Match section-count tendency, theorem density, caption-length distribution, sentence cadence, math display ratio, citation style.
• Never copy prose, claims, examples, or terminology from anything reachable through the cache.
• Never pass — style-ref (or the cache contents) to reviewer / auditor sub-skills — Phase 4.5 (/proof-checker), Phase 4.7 / 5.5 (/paper-claim-audit), Phase 5 (/auto-paper-improvement-loop reviewer), Phase 5.8 (/citation-audit) MUST run on the artifact alone. Cross-model review independence (../shared-references/reviewer-independence.md).

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:

• lite / balanced → draft (default, zero change from current behavior)
• max / beast → submission

1. Default: draft

Action:

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

What each level does downstream:

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

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

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

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

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"

If — style-ref: was passed in $ARGUMENTS and the helper succeeded above, append — style-ref: to the invocation: /paper-plan " — style-ref: ". (Writer-side phase — forwarding is allowed; reviewer/auditor phases below must not see the style ref.)

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-6-Astra 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 1.5.
• User requests changes → adjust plan and re-present.

Phase 1.5: Negotiated Acceptance Contract (before any writing)

The plan says what the paper will contain; the CONTRACT says what "done" means — a checklist of testable assertions, negotiated ADVERSARIALLY before the first section is written, and graded at the end. (The plan is the boundary; the contract is what gets graded.)

PAPERACCEPTANCECONTRACT.md: 10–20 testable assertions covering — every headline claim has a named evidence source (file/table); every number in the abstract traces to a results file; scope qualifiers the title /abstract must carry; figures that must exist and what each must show; section-level completeness (e.g. "limitations names ≥2 real limitations, not hedges"); venue constraints (page limit, anonymization). Each assertion must be CHECKABLE by reading the final PDF + results files — no vibes ("writing is clear" is not an assertion; "every acronym is defined at first use" is). Fewer than ~10 assertions and the gate rubber-stamps; beyond ~20 the negotiation stalls on trivia.

1. Executor proposes. From PAPERPLAN.md + NARRATIVEREPORT.md, draft

1. Reviewer pushes back (fresh thread — the negotiation is adversarial):

mcp__codex__codex:
     model: gpt-6-astra
     config: {"model_reasoning_effort": "xhigh"}
     prompt: |
       You are negotiating the acceptance contract for a paper BEFORE it is
       written. Read these files directly:
       - Plan: <abs path>/PAPER_PLAN.md
       - Proposed contract: <abs path>/PAPER_ACCEPTANCE_CONTRACT.md
       - Evidence inventory: <abs path>/NARRATIVE_REPORT.md (+ results/ paths)

       Push back on the contract, not the plan: (a) assertions that are
       untestable or vibes — demand a checkable rewrite; (b) missing
       assertions — claims in the plan that no assertion covers, numbers with
       no traceability assertion, foreseeable overclaim risks with no scope
       assertion; (c) assertions the evidence inventory cannot possibly
       satisfy — flag now, not after writing. End with exactly one line:
       CONTRACT_ACCEPTED: yes    or    CONTRACT_ACCEPTED: no
       followed by your numbered revision demands if no.

       === SCOPE LIMITS (these bound what you PROPOSE, never what you look for) ===
       Report anything that is actually wrong here — including a rare-looking case, if
       this repo actually produces it. Then keep the fix

A reply with a missing or malformed CONTRACT_ACCEPTED: line is treated as no; request a corrected verdict via codex-reply — that correction exchange does not consume a negotiation round.

mcpcodexcodex-reply (same thread — the negotiation is one conversation). Max 3 rounds.

1. Iterate. On no, revise the contract per the demands and resubmit via