write-paper

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:

• CLAUDE.md — project name, author, institution
• 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.

---

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 (e.g., "no summary statistics table found").

---

Step 3: Propose Outline (WAIT FOR APPROVAL)

Draft a paper outline using standard social science structure:

1. Abstract
2. Introduction
3. Related Literature
4. Data and Institutional Background
5. Empirical Strategy
6. Results
7. Robustness and Extensions
8. Conclusion
References

Present the outline with a one-sentence description of each section's content, linking specific output files to each section (e.g., "Table 2 → Section 6, 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 section — describe the dataset, summary statistics. Reference output/tables/summary_stats.tex if it exists.
2. Empirical Strategy — describe the identification approach from the research spec.
3. Results — one paragraph per main finding. Reference each table/figure with \input{} or \includegraphics{} — do NOT copy table content inline.
4. Robustness — brief description of robustness checks, referencing additional output files.
5. Literature — synthesize from the lit review document if one exists.
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.
8. Conclusion — summarize and state limitations and next steps.

---

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.

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

---

Step 6: Run Domain Review

After saving the draft, launch the domain-reviewer agent via Task:

Task prompt: "Review the draft at manuscripts/[filename] for argument structure, identification assumptions, and citation fidelity. Check that the identification strategy is clearly stated, assumptions are explicit, and all cited tables/figures exist in output/."

Task agent: domain-reviewer

Wait for the review to complete, then present the findings to the user.

---

Step 7: Recommend Next Steps

Inform the user:

• /review-paper — for a full top-journal-style review of the manuscript
• /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 isn't in output/, flag it rather than guessing.
• Report only. The domain-reviewer agent proposes fixes; you apply them only after user approval.