writeup

name	writeup
description	Generate a complete LaTeX research paper from experiment results — including citation gathering, figure descriptions, and iterative refinement.

Paper Writeup

You are writing a complete research paper based on experiment results.

Arguments

• --exp-dir <path>: Experiment directory (required)
• --type <icbinb|icml>: Paper template type — icbinb (4-page workshop) or icml (8-page, default: icbinb)
• --cite-rounds <N>: Number of citation gathering rounds (default: 5)
• --reflections <N>: Number of writeup reflection rounds (default: 3)

Parse from the user's message.

Procedure

1. Load Experiment Context

Read the experiment artifacts:

# Idea description
cat <exp_dir>/idea.md

# Experiment state
python3 -c "
import json, sys
sys.path.insert(0, '.')
from tools.state_manager import load_experiment_state
state = load_experiment_state('<exp_dir>')
print(json.dumps(state, indent=2))
"

Read the best experiment code from the final completed stage. Read stage summaries and journal data for all stages to understand the full experimental narrative.

2. Setup LaTeX Directory

python3 tools/latex_compiler.py setup <exp_dir>/latex --type <icbinb|icml>

Create empty references file:

touch <exp_dir>/latex/references.bib

Copy figures into the LaTeX directory (template uses \graphicspath{{./figures/}}):

mkdir -p <exp_dir>/latex/figures
cp <exp_dir>/figures/*.png <exp_dir>/figures/*.pdf <exp_dir>/latex/figures/ 2>/dev/null || true

3. Gather Citations (up to cite-rounds iterations)

First, check search backend availability:

python3 tools/search.py check

If S2 API is unreachable or rate-limited, use WebSearch exclusively for all citation searches below. Do not waste rounds retrying a broken S2 backend.

For each round:

1. Identify sections with uncited claims (look for statements without \cite{})

2. Formulate 2-3 targeted search queries for the needed citations

3. Search for papers — try S2 first, fall back to WebSearch immediately on failure:

   python3 tools/search.py "<citation query>" --limit 5 --json
   

   If this returns no results or exits with error, use WebSearch to search arxiv.org, scholar.google.com, or semanticscholar.org directly. Extract title, authors, year, venue from the search results.

4. For each relevant paper, add a BibTeX entry to references.bib:

   cat >> <exp_dir>/latex/references.bib << 'BIB_EOF'
   @article{authorYYYYkeyword,
     title={Paper Title},
     author={Author Names},
     journal={Venue},
     year={YYYY},
   }
   BIB_EOF
   

5. Update the paper text with \cite{key} for the added reference.

6. Validate — every \cite{key} must have a matching references.bib entry. No fabricated references.

Stop early when all major claims are cited (typically 10-20 for a workshop paper, 20-35 for a full paper). Do not force all rounds if citations are sufficient.

4. View and Describe Figures (VLM Review)

Use Claude's native vision capabilities to review each figure.

List all figures in <exp_dir>/figures/:

ls <exp_dir>/figures/*.png <exp_dir>/figures/*.pdf 2>/dev/null

View each figure using the Read tool. For each figure, analyze:

1. Description: What does the figure show? What data is represented?
2. Quality: Is the figure publication-ready? (axis labels, legends, resolution)
3. Key Finding: What is the main takeaway from this figure?
4. Caption Draft: Write a suggested figure caption (1-3 sentences)
5. Redundancy Check: Are any figures duplicates or near-duplicates? If so, select the best one and flag others for removal.
6. Relevance: Does this figure support a key claim in the paper? If not, consider moving to appendix or removing.

Build a figure description string that will be injected into the paper generation prompt. This ensures the LaTeX generator knows what each figure shows and can reference them accurately.

5. Generate LaTeX Paper

Write the complete paper content into template.tex. The paper structure should be:

For ICBINB (4-page):

1. Title — concise, informative
2. Abstract — adapted from the idea, updated with actual results
3. Introduction — motivation, problem, contributions (cite related work)
4. Method — technical description of the approach (from best experiment code)
5. Experimental Setup — datasets, baselines, hyperparameters, evaluation metrics
6. Results — key findings with figure references (\ref{fig:...})
7. Discussion — interpretation, limitations, comparison to prior work
8. Conclusion — summary and future work
9. References — via \bibliography{references}

For ICML (8-page):

Same structure plus:

• Related Work — expanded section
• Ablation Studies — from Stage 4 results
• Background — formal problem setup
• Appendix with additional results

LaTeX Requirements:

• Replace the placeholder sections in template.tex between %%%%%%%%%SECTION%%%%%%%%% markers
• Use \begin{figure} with \includegraphics{<filename>} for plots (graphicspath handles the directory)
• Use \cite{key} for citations matching references.bib keys
• Use proper math notation (\mathbb{R}, \mathcal{L}, etc.)
• Ensure all figures are referenced in the text
• Keep within page limits (4 for icbinb, 8 for icml, excluding references)

6. Compile and Check

python3 tools/latex_compiler.py compile <exp_dir>/latex --main template.tex

Check for errors:

python3 tools/latex_compiler.py pages <exp_dir>/latex/template.pdf

If there are LaTeX errors, read the log file and fix them:

cat <exp_dir>/latex/template.log | grep -A 2 "^!" | head -20

7. Reflection Loop (up to N rounds)

For each reflection round:

1. Check the compiled PDF page count — ensure within limits
2. Run chktex for LaTeX warnings (if available)
3. Re-read the paper content critically:
   • Is the abstract accurate given the actual results?
   • Are all figures referenced and described?
   • Are all citations used in the text?
   • Is the writing clear and concise?
   • Are there any LaTeX errors or formatting issues?
4. Make improvements and recompile

If everything looks good, declare "I am done" and exit the loop.

8. Finalize

Move the final PDF:

cp <exp_dir>/latex/template.pdf <exp_dir>/paper.pdf

Report:

• Paper path: <exp_dir>/paper.pdf
• Page count
• Number of citations
• Number of figures

Writing Guidelines

• Write in formal academic style (third person, passive voice where appropriate)
• Be precise about experimental details — exact hyperparameters, dataset sizes, metrics
• Present negative results honestly — this is especially important for ICBINB
• Use consistent terminology throughout
• Every claim should be supported by experimental evidence or citations
• Avoid overclaiming — use "suggests" instead of "proves" for empirical results