init

What this skill does

# Papermill Init

Initialize a paper repository for use with papermill. Follow every step below in order. Be thorough in discovery but conservative in action -- never overwrite existing state.

---

## Step 1: Check for Existing State

Check for state files in this order (Read tool):

1. **`.papermill/state.md`** (current format)
2. **`.papermill.md`** (legacy format — needs migration)

### Case A: `.papermill/state.md` exists

Read it, display a summary (title, stage, format, authors), then offer refresh:

  > This repository is already initialized. Current state is shown above.
  >
  > Would you like to **refresh** the state file? This will:
  > - Add any missing YAML fields from the current schema (preserving all existing data)
  > - Re-discover repo structure for new files or assets
  > - Ask about anything not yet captured (e.g., related papers)
  >
  > Nothing will be overwritten or removed. Or use `/papermill:status` for a quick look.

  If the user declines refresh, stop here. If they accept, proceed to **Refresh Mode** below.

### Case B: `.papermill.md` exists (legacy)

Migrate to the new directory structure:

1. Create `.papermill/` directory and `.papermill/reviews/` subdirectory (Bash tool: `mkdir -p .papermill/reviews`)
2. Read `.papermill.md` content
3. Write it to `.papermill/state.md` (Write tool)
4. Delete `.papermill.md` (Bash tool: `rm .papermill.md`)
5. Tell the user:

  > **Migrated state file.** Moved `.papermill.md` → `.papermill/state.md` and created `.papermill/reviews/` for review output. All existing data preserved.

Then display the summary and offer refresh as in Case A.

### Case C: No state file found

Continue to Step 2 (fresh initialization).

---

## Refresh Mode

Refresh is **additive only** -- it fills gaps without touching existing data. Run through each check below, report what was found, and apply changes only with user confirmation.

### 1. Schema migration

Compare the existing YAML frontmatter against the current schema (shown in Step 7). For each field in the schema that is missing from the file, add it with its default value. Common cases:

- Missing `thesis` block → add with empty `claim`, `novelty`, `refined: null`
- Missing `prior_art` block → add with empty defaults
- Missing `experiments` → add as `[]`
- Missing `venue` block → add with `target: null`, `candidates: []`
- Missing `review_history` → add as `[]`
- Missing `related_papers` → add as `[]`
- Missing `authors[].orcid` → add as `""`

Report what was added: "Added N missing fields to bring the state file up to the current schema." If nothing is missing, say so.

### 2. Re-discover repo structure

Run the same discovery as Step 2 (format detection, asset scan). Compare against what the state file already records. Report any new findings:

- New `.bib` files since initialization
- New code directories (`research/`, `scripts/`, etc.)
- Format change (e.g., repo now has `.Rmd` files but format says `latex`)

For format mismatches, ask the user: "The state file says `latex` but I also found `.Rmd` files. Should I update the format?" Only update with confirmation.

### 3. Fill in missing context

Check for content that the current init flow captures but older versions may not have asked about:

- **Related papers (Step 6)**: If `related_papers` is empty or missing, run the repoindex discovery query (if `repoindex` is available) and present any papermill-tracked projects found. Also re-ask the Step 6 question about related work and software. If `related_papers` is already populated, still offer repoindex discovery to catch newly-initialized projects: "You have N related papers linked. Want me to check for any new papermill-tracked projects?"
- **Related work and software (Step 6)**: If the Notes section does not contain a `## Related Work` heading, run the related-work question from Step 6. If the user provides context, append it to the notes.
- **Author ORCID**: If `authors[].orcid` is empty, check `deets` and offer to fill it in.
- **Title**: If `title` is empty or looks like a placeholder, re-run title inference from Step 4.

### 4. Report and finish

Display what changed:

> **Refresh complete.**
>
> | Action | Details |
> |--------|---------|
> | Schema fields added | N (list them) |
> | New assets discovered | (list or "none") |
> | Context updated | (what was added or "nothing new") |

Append a timestamped note to the markdown body:

```
- YYYY-MM-DD (init refresh): Refreshed state file. [brief summary of changes].
```

Do NOT modify existing field values (stage, thesis, prior_art content, experiments, reviews, venue selections) unless the user explicitly asks. Those are managed by their respective skills.

---

## Step 2: Discover Repository Structure

Search the repository to understand what kind of paper project this is (Glob tool). Look for all of the following and report what you find:

### Format detection (check in this order)

1. **LaTeX**: Search for `*.tex` files (Glob tool). If found, set `format: latex`.
2. **R Markdown**: Search for `*.Rmd` files (Glob tool). If found, set `format: rmarkdown`.
3. **Markdown**: Search for `paper.md`, `manuscript.md`, or any markdown file that looks like a JOSS-style paper (contains `title:` in YAML frontmatter) (Glob/Grep tools). If found, set `format: markdown`.
4. If none of the above are found, ask the user what format they plan to use. Default to `format: latex` if they are unsure.

### Additional assets

- `*.bib` files (bibliography)
- `research/` or `code/` or `scripts/` or `analysis/` directories (computational work)
- `CITATION.cff` (citation metadata)
- `figures/` or `img/` or `images/` directories (graphics)
- `Makefile`, `latexmkrc`, or build configuration files
- `README.md` or `CLAUDE.md` (project documentation)

Report a brief inventory of what was found, for example:

> **Discovered structure:**
> - Format: latex (found `paper/main.tex`)
> - Bibliography: `paper/references.bib` (12 entries)
> - Research code: `research/` directory present
> - Figures: `figures/` directory with 3 PDF files
> - Build system: `latexmk` configuration found

---

## Step 3: Get Author Information

Try to obtain the primary author's identity using the `deets` CLI tool, which manages personal metadata (Bash tool).

Run these commands (each may fail if deets is not installed -- that is fine):

```bash
deets get identity.name
deets get contact.email
deets get academic.orcid
```

- **If `deets` is available** and returns values: Use them as the primary author. Show the user what was found and ask for confirmation.
- **If `deets` is not available** or returns errors: Ask the user directly:
  > I could not find author information via `deets`. Please provide:
  > 1. Your full name (as it appears on papers)
  > 2. Your email address
  > 3. Your ORCID (optional, e.g., 0000-0002-1234-5678)

Also check for author info in existing files (Read/Grep/Bash tools):
- `\author{}` blocks in `.tex` files
- `CITATION.cff` author fields
- Git config (`git config user.name`, `git config user.email`)

If multiple sources conflict, prefer: deets > tex file > CITATION.cff > git config. Always confirm with the user.

---

## Step 4: Infer the Paper Title

Attempt to extract the title automatically (Grep/Read tools):

- **LaTeX**: Search for `\title{...}` in `.tex` files. Handle multiline titles and macro-containing titles.
- **Markdown/R Markdown**: Look for the first `# heading` or a `title:` field in YAML frontmatter.
- **CITATION.cff**: Check the `title:` field.

If a title is found, show it to the user and ask for confirmation. If no title is found, ask:

> I could not detect a paper title. What is the working title for this paper?

---

## Step 5: Infer the Current Stage

Determine the project stage based on what exists in the repository:

| Condition | Stage |
|-----------|-------|
| No paper content files exist (empty or new repo) | `idea` |
| Only outline/notes exist, minimal prose | `outlining` |
| Substantial paper cont