Write Paper

Paper Writing

Don't ask permission. Just do it.

Use this skill for experiment-driven or systems-style papers.

Do not use this for pure survey writing. For literature reviews or thesis review chapters, use /write-review-paper instead.

Outputs go to paper/.

Prerequisites

You need a real evidence base from existing artifacts, ideally:

• experiment_res.md
• one or more figure files
• one or more comparison tables / result summaries
• optional support from survey_res.md, plan_res.md, ml_res.md

If the evidence base is too thin, write the draft conservatively and mark unsupported sections as TODO.

Required Outputs

• paper/claim_inventory.md
• paper/figures_manifest.md
• paper/draft.md
• paper/manuscript.tex
• paper/sections/*.tex
• paper/references.bib
• paper/build_paper.sh
• paper/build/build.log
• paper/build/manuscript.pdf when the build succeeds
• paper/build/build_errors.md when the build fails

Optional Supporting Outputs

• paper/boundary_notes.md
• venue- or artifact-specific optional sections such as:
  • paper/sections/ablations.tex
  • paper/sections/discussion_scope.tex
  • paper/sections/related_work.tex

Workflow

Step 1: Build the Claim Inventory

Before drafting prose, create claim_inventory.md.

Each claim entry must use the same fixed fields:

• claim_id
• claim_text
• claim_type (result, observation, or interpretation)
• source_files
• figure_or_table_anchor
• baseline
• protocol_or_guardrail
• evidence_type (simulator, local_runtime, or runtime)
• confidence (high, medium, or low)
• allowed_in_sections (abstract, intro, results, discussion, conclusion, boundary_note)

Use references/evidence-contract.md and references/claim-inventory-template.md.

Step 2: Build the Figures Manifest

Create figures_manifest.md as the shared contract for claim support, prose callouts, captions, and LaTeX figure blocks.

Each figure entry must include:

• figure_id
• file_path
• latex_label
• section
• placement_hint
• caption_short
• caption_long
• takeaway_sentence
• callout_sentence
• baseline
• evidence_type
• source_metrics
• source_files
• supports_claim_ids
• must_appear_before_claim_ids

Use:

• references/figures-manifest-template.md
• references/figure-callout-template.md

Treat this manifest as the single source of truth for:

• which claim a figure supports
• where the figure belongs in the paper
• what the first text callout should say
• what goes into the short and long caption
• what the eventual LaTeX block should render

If a result is intentionally table-only or text-only evidence, say that explicitly in the relevant results paragraph instead of inventing a figure placeholder.

Step 3: Draft the Paper

Write draft.md using:

• references/paper-template.md
• references/paragraph-contract.md
• references/style-banlist.md
• references/paragraph-examples.md

Then populate the LaTeX starter bundle under paper/:

• update paper/manuscript.tex
• fill the core sections under paper/sections/*.tex
• add optional sections only when they materially help the current paper
• keep paper/references.bib aligned with the draft when citations are ready
• make paper/sections/main_results.tex consistent with paper/figures_manifest.md

Treat the manuscript as a composable section set, not a fixed checklist. The default core path is:

• abstract
• introduction
• problem_setup
• method_system
• experimental_protocol
• main_results
• conclusion

Optional modules should be chosen based on venue, evidence profile, and paper shape:

• ablations
• discussion_scope
• related_work

Choose a paper shape before filling sections:

• result_note
  • use the core path only
  • keep boundary handling in main_results, conclusion, or paper/boundary_notes.md
• systems_full
  • use the core path plus whichever optional modules materially help
  • add discussion_scope only when interpretation and evidence boundary need a dedicated home
• artifact_summary
  • keep the structure lean and evidence-first
  • prefer short results plus a compact conclusion boundary note over extra sections
• workshop_short
  • compress setup and method aggressively
  • avoid optional sections unless they carry real argumentative weight

Every result paragraph must stay within the claim inventory. If the evidence only supports a narrower claim, write the narrower claim.

Use this section contract while drafting:

• Abstract may only use claims with confidence=high.
• Introduction may use problem framing and setup claims, but must not introduce new result claims.
• Results must anchor each substantive paragraph to at least one claim_id.
• Discussion may interpret results, but interpretation must remain explicitly separated from observed outcomes.
• Boundary and caveat handling must explicitly cover evidence boundaries, missing validations, and unsupported comparisons somewhere in the paper.
• Future Work is the only place where unsupported but plausible ideas may appear.

Use the figures manifest as a hard drafting contract:

• every headline result claim must map to at least one supports_claim_ids entry in paper/figures_manifest.md, unless the paragraph explicitly states that the evidence is table-only or text-only
• the first prose mention of a figure must use or closely follow its callout_sentence
• a figure callout must appear before the figure block or at the first figure discussion point
• caption_short, caption_long, latex_label, file_path, and placement_hint must stay aligned with the eventual LaTeX figure block
• if a claim needs figure support but no manifest entry names it in supports_claim_ids, do not treat that claim as ready for the main results section

Use these paragraph-level rules:

• Every results paragraph must contain at least one quantitative statement.
• Every comparison sentence must explicitly name a baseline or comparison target.
• Every interpretation sentence must be clearly distinguishable from the observed evidence it builds on.
• Avoid adjective inflation when a metric, baseline, or evidence path would be more precise.
• If a paragraph only restates a figure without adding a takeaway or boundary, rewrite it.

Stop Conditions

Do not continue into a full results draft if any of the following is true:

• experiment_res.md is missing and no equivalent result artifact exists.
• No figure or table anchor exists for a headline result.
• A claimed improvement has no explicit baseline.
• A result claim has no source file or no protocol / guardrail.
• paper/figures_manifest.md is missing for a figure-backed results section.
• a required figure entry is missing section, placement_hint, callout_sentence, or supports_claim_ids

If one of these conditions is triggered, stop after writing claim_inventory.md and a boundary/caveat note, and mark the blocked sections in draft.md as TODO.

Do not write a results paragraph if:

• it cannot be tied to a claim_id
• it has no quantitative statement
• it makes a comparison without naming a baseline
• it implicitly depends on a figure but the manifest does not specify the figure contract

Step 4: Choose the Boundary Surface

Do not treat Limitations as a default section.

Choose the lightest surface that still makes the evidence boundary explicit:

• a dedicated discussion_scope section
• a short boundary paragraph in Conclusion
• a short caveat paragraph in Main Results
• a standalone paper/boundary_notes.md during drafting

Use a dedicated limitations section only when the venue, review criteria, or artifact risk explicitly requires it.

If you need a drafting aid, use references/boundary-notes-template.md.

Step 5: Build the PDF

Run bash paper/build_paper.sh.

The build chain should:

• write compiler output to paper/build/build.log
• produce paper/build/manuscript.pdf when successful
• write paper/build/build_errors.md when the build fails or when tectonic is unavailable

Step 6: Hand Off to the Release Gate

Do not treat the manuscript as ready to share immediately after the PDF build succeeds.

Before external sharing, run /artifact-review so the workspace also has:

• review/artifact_review.md
• review/release_checklist.md
• review/release_gate.json

Treat release readiness as unverified until the release gate is fresh and not HOLD.

Writing Rules

1. No headline metric without baseline + protocol + source path.
2. No simulator-only result should be phrased as runtime validation.
3. Distinguish observed result from interpretation.
4. Keep unsupported ideas in a clearly marked future-work section, not in the main results.
5. Do not place a claim in a section that is not listed in its allowed_in_sections.
6. Do not use empty praise words where a metric, baseline, or scope boundary should appear.