paper-creator

What this skill does

# Scientific Paper Creator

Write publication-quality scientific papers in LaTeX with a **test-driven workflow**: every section is compiled and verified before moving to the next. The paper is never in a broken state.

## Bundled Resources

This skill includes ready-to-use scripts and templates. Paths are relative to the skill directory (find it via `glob("**/KORTIX-paper-creator/")`):

| Resource | Path | Purpose |
|----------|------|---------|
| **LaTeX template** | `assets/template.tex` | Minimal IMRaD template -- copy to `main.tex` |
| **BibTeX generator** | `scripts/openalex_to_bibtex.py` | Convert OpenAlex API JSON to `.bib` entries |
| **Compiler** | `scripts/compile.sh` | `pdflatex + bibtex` pipeline with error reporting |
| **Verifier** | `scripts/verify.sh` | TDD verification suite (12 checks) |

## The TDD Rule

**After writing every section:**

```
1. WRITE section → sections/{name}.tex
2. COMPILE: bash compile.sh paper/{slug}/main.tex
3. VERIFY:  bash verify.sh paper/{slug}/
4. If FAIL → FIX → go to 2
5. If PASS → move to next section
```

The paper must compile and pass verification at every step. Never batch errors. Never skip verification. This is non-negotiable.

## Pipeline Overview

```
Phase 1: SCAFFOLD  →  Create project, copy template, initialize empty sections
                       Verify: compiles to valid (empty) PDF ✓

Phase 2: CITE      →  Search literature (OpenAlex), build references.bib
                       Verify: bibliography builds without errors ✓

Phase 3: WRITE     →  Per-section composition in writing order
                       Verify: compile + verify after EACH section ✓

Phase 4: POLISH    →  Self-reflection pass, strict verification, final build
                       Verify: verify.sh --strict passes with zero warnings ✓
```

## Filesystem Architecture

```
paper/{paper-slug}/
├── main.tex                    # Master file (\input sections)
├── references.bib              # BibTeX bibliography
├── sections/
│   ├── abstract.tex
│   ├── introduction.tex
│   ├── related-work.tex
│   ├── methods.tex
│   ├── results.tex
│   ├── discussion.tex
│   └── conclusion.tex
├── figures/                    # .pdf/.png figures (+ generation scripts)
├── data/                       # Supporting data, CSVs (optional)
└── build/                      # Compilation output
    └── main.pdf
```

## Phase 1: Scaffold

### 1a. Create project structure

```bash
SLUG="paper-slug-here"
mkdir -p "paper/$SLUG"/{sections,figures,data,build}
```

### 1b. Copy and adapt the template

```bash
SKILL_DIR=$(find . -path "*/KORTIX-paper-creator/assets/template.tex" -exec dirname {} \; | head -1 | sed 's|/assets||')
cp "$SKILL_DIR/assets/template.tex" "paper/$SLUG/main.tex"
```

Edit `main.tex`: set `\title{}`, `\author{}`, and adapt `\documentclass` if targeting a specific venue:

| Venue | Document class | Notes |
|-------|---------------|-------|
| General / arXiv | `\documentclass[11pt,a4paper]{article}` | Default in template |
| IEEE conference | `\documentclass[conference]{IEEEtran}` | Remove geometry package |
| ACM conference | `\documentclass[sigconf]{acmart}` | Remove geometry, use acmart bib style |
| Springer LNCS | `\documentclass{llncs}` | Remove geometry, use splncs04 bib style |

### 1c. Initialize section stubs

Create each section file with a section header and TODO marker:

```bash
for sec in abstract introduction related-work methods results discussion conclusion; do
    SECTION_TITLE=$(echo "$sec" | sed 's/-/ /g; s/\b\(.\)/\u\1/g')
    if [ "$sec" = "abstract" ]; then
        echo '\begin{abstract}' > "paper/$SLUG/sections/$sec.tex"
        echo "% TODO: Write abstract" >> "paper/$SLUG/sections/$sec.tex"
        echo '\end{abstract}' >> "paper/$SLUG/sections/$sec.tex"
    else
        echo "\\section{$SECTION_TITLE}" > "paper/$SLUG/sections/$sec.tex"
        echo "\\label{sec:$sec}" >> "paper/$SLUG/sections/$sec.tex"
        echo "% TODO: Write $sec" >> "paper/$SLUG/sections/$sec.tex"
    fi
done
```

### 1d. Initialize empty bibliography

```bash
echo "% References for $SLUG" > "paper/$SLUG/references.bib"
echo "% Generated by openalex_to_bibtex.py and manual entries" >> "paper/$SLUG/references.bib"
```

### 1e. VERIFY: First green state

```bash
bash "$SKILL_DIR/scripts/compile.sh" "paper/$SLUG/main.tex"
bash "$SKILL_DIR/scripts/verify.sh" "paper/$SLUG/"
```

The empty paper must compile cleanly. This is your baseline. Every subsequent change maintains this green state.

## Phase 2: Literature & Citations

### 2a. Search for papers

Load the `openalex-paper-search` skill for OpenAlex API reference. Search strategy:

```bash
# Seminal/highly-cited papers
curl -s "https://api.openalex.org/works?search=YOUR+TOPIC&filter=cited_by_count:>50,type:article,has_abstract:true&sort=cited_by_count:desc&per_page=15&select=id,display_name,publication_year,cited_by_count,doi,authorships,abstract_inverted_index&[email protected]"

# Recent work (last 2-3 years)
curl -s "https://api.openalex.org/works?search=YOUR+TOPIC&filter=publication_year:>2023,type:article&sort=publication_date:desc&per_page=15&[email protected]"

# Review/survey papers
curl -s "https://api.openalex.org/works?search=YOUR+TOPIC&filter=type:review&sort=cited_by_count:desc&per_page=10&[email protected]"
```

### 2b. Generate BibTeX entries

Pipe OpenAlex results through the converter:

```bash
curl -s "https://api.openalex.org/works?search=YOUR+TOPIC&per_page=20&[email protected]" | \
    python3 "$SKILL_DIR/scripts/openalex_to_bibtex.py" >> "paper/$SLUG/references.bib"
```

For non-OpenAlex sources (web pages, books, reports), add manual BibTeX entries:

```bibtex
@misc{authorYYYYtitle,
  title = {Page Title},
  author = {Author Name},
  year = {2024},
  url = {https://example.com/page},
  note = {Accessed: 2024-01-15}
}

@book{authorYYYYbook,
  title = {Book Title},
  author = {First Author and Second Author},
  year = {2024},
  publisher = {Publisher Name},
  edition = {2nd}
}
```

### 2c. VERIFY: Bibliography builds

```bash
bash "$SKILL_DIR/scripts/compile.sh" "paper/$SLUG/main.tex"
bash "$SKILL_DIR/scripts/verify.sh" "paper/$SLUG/"
```

Check: zero BibTeX errors, all `.bib` entries parse correctly.

## Phase 3: Per-Section Writing

### Writing Order

Write sections in this order (each one builds on context from the previous):

1. **Abstract** (draft) -- establishes scope, will be revised last
2. **Introduction** -- context, problem, gap, contribution
3. **Methods** -- what you did and how
4. **Results** -- what you found
5. **Discussion** -- what it means, limitations
6. **Related Work** -- needs full paper context to position contribution
7. **Conclusion** -- recap, future work
8. **Abstract** (final) -- revise to match actual paper content

### The Writing Loop (for each section)

```
1. READ all previously written sections to build context
2. WRITE the section following the guidance below
3. COMPILE + VERIFY
4. SELF-REFLECT: re-read critically
   - Every factual claim has a \cite{}?
   - No filler words or empty hedging?
   - Logical flow between paragraphs?
   - Consistent with other sections?
   - Quantitative where possible?
5. REVISE if needed → COMPILE + VERIFY again
6. Section DONE → next
```

### Section-Specific Guidance

#### Abstract (150-300 words)

Structure: **Context** (1-2 sentences) → **Problem** → **Approach** → **Key results** (quantitative!) → **Implications**.

```latex
\begin{abstract}
[Context sentence setting the broad area.]
[Problem: what gap or challenge exists.]
[Approach: what this paper does -- "We propose/present/introduce..."]
[Results: key quantitative findings -- "Our method achieves X\% on Y, outperforming Z by N\%."]
[Implications: why it matters.]
\end{abstract}
```

Rules: No citations in abstract. No undefined acronyms. Every number must appear in the actual results.

#### Introduction

**Funnel structure:** broad context → specific problem → gap in existing work → your contribution → paper outline.