write-paper

name	write-paper
description	Draft an academic paper from analysis outputs and project materials.

Write Paper Draft

Draft an academic manuscript from existing analysis outputs. Follows propose-first — the outline is always shown for approval before writing begins.

Input: $ARGUMENTS — a paper title, research question, or from spec to read from quality_reports/specs/.

---

Step 1: Orient

Read project context:

• PROJECT_CONTEXT.md — project name, author, institution
• references/domain-profile.md — field conventions and target venues
• Most recent file in quality_reports/specs/ — research question and identification strategy
• Most recent file in quality_reports/lit_review_*.md — related literature (if it exists)
• Most recent file in quality_reports/research_ideation_*.md — hypotheses (if it exists)

If no spec exists, ask the user for the core research question before proceeding.

Use references/domain-profile.md to calibrate writing style and section emphasis. A political science paper should not read like an econometrics note; mirror the conventions of the project's field rather than forcing a single voice.

---

Step 2: Inventory Analysis Outputs

Glob for available outputs:

• output/tables/**/*.tex — regression tables
• output/tables/**/*.html — HTML table versions
• output/figures/**/*.pdf, output/figures/**/*.png — figures
• output/**/*.rds, output/**/*.pkl, output/**/*.parquet — saved objects

List what exists. Note any gaps (for example, "no summary statistics table found").

---

Step 3: Propose Outline (WAIT FOR APPROVAL)

Draft a paper outline using this standard structure:

1. Abstract
2. Introduction
3. Background
4. Data & Methods
5. Results
6. Discussion
7. Appendix
References

The structure is flexible. Default to the outline above unless:

• the user requests a different structure, or
• the field in references/domain-profile.md has strong conventions that warrant a different organization.

If you deviate from the default, explain why before drafting.

Present the outline with a one-sentence description of each section's content, linking specific output files to each section (for example, "Table 2 -> Section 5, Results"). Do NOT start writing until the user approves the outline or requests changes.

---

Step 4: Draft Section by Section

Write in this order (minimizes backtracking):

1. Data & Methods — describe the dataset and summary statistics, then the identification or estimation approach from the research spec.
2. Results — one paragraph per main finding. Reference each table or figure with \input{} or \includegraphics{}. Do NOT copy table content inline.
3. Discussion — interpret the findings, discuss robustness checks, acknowledge limitations, and state implications.
4. Appendix — additional robustness tables, derivations, and supplementary figures. Reference output files only.
5. Background — synthesize the literature review if it exists and position the contribution against prior work.
6. Introduction — write after results are known. State the question, preview the findings, and map the paper.
7. Abstract — write last: one sentence each for motivation, question, method, finding, and implication.

---

Step 5: Save the Draft

Save to manuscripts/[project-name]-draft.tex (or .qmd if the user prefers Quarto).

Create manuscripts/ directory if it does not exist.

If output format is not already clear from the repo or the user's request, use request_user_input in Plan mode for a single-choice prompt if available; otherwise ask conversationally:

• header: "Format"
• question: "Which manuscript format should I draft in?"
• options:
  • label: "LaTeX (Recommended)", description: "Best fit for existing manuscript and table workflows"
  • label: "Quarto", description: "Good if the project already uses .qmd authoring"

Use \input{} for tables and \includegraphics{} for figures — reference the actual files in output/, do not embed content directly.

---

Step 6: Structural Smoke Test

Before handing off to proofread, review-paper, or revise-paper, run a quick structural check on the saved draft. This is not a substance review — it is a drafting-artifact check.

Read the draft and verify:

1. Table references resolve. For every \input{...} command in the draft, confirm the referenced file exists in output/.
2. Figure references resolve. For every \includegraphics{...} command, confirm the referenced file exists in output/figures/.
3. No placeholders remain. Search for TODO, FIXME, XXX, [placeholder], [TK], ???, and square-bracketed all-caps tokens such as [PLACEHOLDER].
4. Required sections are present. Confirm the draft contains an abstract, an introduction, and a conclusion (or the field-appropriate equivalent heading).
5. No obvious orphaned numbers. When prose contains numeric claims, check whether they appear near a referenced output file. This is heuristic — flag likely orphans rather than guessing.

Present the results as a short checklist:

## Structural Smoke Test Results

[OK]      Table references: 8/8 resolve
[FAIL]    Figure references: 3/4 resolve — missing output/figures/heterogeneity.pdf
[OK]      No placeholders found
[OK]      Required sections present
[WARN]    4 numeric claims in prose may lack nearby output references — see notes

If the smoke test flags issues, offer to fix them before the next review step.

---

Step 7: Recommend Next Steps

Inform the user:

• proofread — for grammar, typos, layout, and consistency
• review-paper — for a multi-perspective top-journal-style review
• revise-paper — to apply an approved review report systematically
• validate-bib — to check all citations are in the bibliography
• quality-gate — to verify every claim in the paper is backed by an output file

---

Key Rules

• Propose outline first. Never start writing without outline approval.
• Reference, don't embed. Tables and figures go in output/; the paper references them by path.
• No fabrication. Only write results that exist in output files. If a number is not in output/, flag it rather than guessing.
• Smoke test, don't substance-review. Step 6 catches drafting artifacts only. Substance review belongs in review-paper.