r-pub-pipeline

What this skill does

# R Package Publication Pipeline

Orchestrate the full publication pipeline for R packages: CRAN submission → JOSS paper → optionally JSS methods paper. This skill coordinates the other skills (`/cran-audit`, `/joss-audit`, `/joss-draft`) into a coherent workflow.

## Strategy

The recommended publication order for R packages:

1. **CRAN** — Distribution, discoverability, installation via `install.packages()`
2. **JOSS** — Quick DOI, peer-reviewed citation, Crossref/Google Scholar indexing
3. **JSS** (optional) — High-prestige methods paper, Web of Science indexed (IF ~5)

Each stage builds on the previous. CRAN gives the package legitimacy. JOSS gives it a citable DOI. JSS gives the methodology academic weight.

## Workflow

### Phase 1: Assess Current State

Start by understanding where the package stands:

**Load user config** (Read tool): Read `.claude/pub-pipeline.local.md` if it exists. Extract author metadata, `r.domain`, `r.audience`, `r.competitors`, `r.targets` (e.g., `["CRAN", "JOSS"]`), and `related_work` from the YAML frontmatter. If `related_work` contains companion papers or preprints, note them, since they affect the JOSS paper (cite companion papers, reference preprint DOIs) and the overall publication strategy.

```
1. Read DESCRIPTION for package metadata (Read tool)
2. Check git log for development history (Bash tool)
3. Look for existing paper.md, CITATION.cff (Glob tool)
4. Check if already on CRAN — search https://cran.r-project.org/package={name} (WebFetch tool)
5. Check if already on JOSS — search joss.theoj.org (WebSearch tool)
```

**Dependency chain** (Bash tool):
Parse `Imports`, `Depends`, and `LinkingTo` from `DESCRIPTION`. For each non-base/non-recommended package, verify it exists on CRAN:
```bash
Rscript -e 'ap <- available.packages(); cat("PKG_NAME" %in% rownames(ap))'
```
If any dependency is not on CRAN, this is a hard blocker — the package cannot pass `R CMD check --as-cran`. Present the submission order (publish dependencies first) and offer to switch to the dependency package. Also check `r.dependency_chain` in the user config for structured dependency status.

**CI status** (Bash/Glob tools):
Check for `.github/workflows/` directory (Glob tool). If present, check recent CI status:
```bash
gh run list --limit 3 --json conclusion,name,headBranch
```
Flag if CI is failing — passing CI is important for CRAN confidence and JOSS reviewer trust.

Classify the package into one of:

| State | Next Step |
|-------|-----------|
| Dependencies not on CRAN | Start with dependency package |
| Not on CRAN, no paper.md | Start with CRAN audit |
| On CRAN, no paper.md | Start with JOSS audit |
| On CRAN, has paper.md | Review paper, prepare JOSS submission |
| On CRAN, published in JOSS | Consider JSS (if substantive methodology) |

**Note**: If the package is bioinformatics-focused (genomics, proteomics, etc.), consider Bioconductor instead of CRAN. Bioconductor has its own submission process and is the standard distribution channel for bioinformatics R packages.

Present the assessment to the user and confirm the plan before proceeding.

### Phase 2: CRAN Readiness

Invoke `/cran-audit` (the `cran-audit` skill) to evaluate CRAN readiness.

If the package is not CRAN-ready:
1. Present the gap report
2. Offer to fix automatable issues
3. Guide manual fixes
4. Re-audit after fixes
5. Walk through submission workflow when ready

If the package is already on CRAN, skip to Phase 3.

**Key CRAN submission steps** (when ready):
1. `usethis::use_version("minor")` — bump version
2. `devtools::check(args = "--as-cran")` — final check
3. Test on other platforms:
   - `devtools::check_win_devel()` — Windows (win-builder)
   - `rhub::check_for_cran()` — Multiple platforms via R-hub
4. `devtools::submit_cran()` — submit
5. Confirm via email link
6. After acceptance: `usethis::use_github_release()`, then `usethis::use_dev_version()`

**If CRAN rejects the submission**:
1. Read the reviewer's email carefully — they identify specific issues
2. Fix all identified issues (do not partially fix)
3. Re-run `devtools::check(args = "--as-cran")` to verify
4. Resubmit via `devtools::submit_cran()` — CRAN allows resubmission
5. In `cran-comments.md`, note what was fixed since the previous submission
6. Do not resubmit more than once per week unless requested by CRAN

### Phase 3: JOSS Readiness

Invoke `/joss-audit` (the `joss-audit` skill) to evaluate JOSS readiness.

Key prerequisites that are often missing:
- **Development history**: Need 6+ months of public git history
- **Contributing guidelines**: `CONTRIBUTING.md` or section in README
- **paper.md**: The JOSS paper itself

If `paper.md` doesn't exist, proceed to Phase 4.

### Phase 4: Draft JOSS Paper

Invoke `/joss-draft` (the `joss-draft` skill) to draft `paper.md` and `paper.bib`.

After drafting:
1. Present the draft to the user for review
2. Iterate on feedback
3. Optionally run the `pub-pipeline:joss-reviewer` agent (via `/joss-audit`) for critical review against the JOSS checklist
4. Commit the paper to the repository

### Phase 5: JOSS Submission

Walk the user through JOSS submission:

1. **Pre-submission checklist**:
   - Package on CRAN (or at minimum, installable from GitHub)
   - `paper.md` and `paper.bib` committed to repository
   - All JOSS reviewer checklist items pass (`/joss-audit`)
   - ORCID for all authors

2. **Submit**:
   - Go to https://joss.theoj.org/papers/new
   - Fill in repository URL and other fields
   - Wait for pre-review issue

3. **During review** (2-6 weeks):
   - Respond to reviewer feedback promptly (target 2 weeks)
   - Make requested changes to code and paper
   - Re-run `/joss-audit` after changes

4. **Post-acceptance**:
   - Create tagged release (e.g., `v1.0.0`)
   - Deposit on Zenodo:
     1. Go to https://zenodo.org and log in with GitHub
     2. Enable the Zenodo-GitHub integration for this repository (Settings → GitHub)
     3. Create a GitHub release (this triggers automatic Zenodo archiving)
     4. Copy the Zenodo DOI from the automatically created deposit
   - Update review issue with version number and Zenodo DOI
   - JOSS assigns paper DOI via Crossref

### Phase 6: JSS Consideration (Optional)

Evaluate whether a JSS (Journal of Statistical Software) paper is warranted:

**JSS is appropriate when**:
- The package implements novel statistical methodology
- There's substantive mathematical content to present (proofs, derivations)
- The paper would be 20-50 pages of methods + software description
- The target audience is academic statisticians

**JSS is NOT appropriate when**:
- The package is primarily a software tool (JOSS covers this)
- The mathematics is textbook material
- The paper would essentially repeat the JOSS paper at greater length

If JSS is appropriate, note that:
- JSS uses `rticles::jss_article` RMarkdown format
- JSS papers are 20-50 pages and include mathematical exposition
- JSS is indexed in Web of Science (Impact Factor ~5)
- Review takes 6-18 months
- The `papermill:writer` agent can help draft a full JSS paper (long-form academic writing)

## Decision Helpers

### Is My Package Publishable?

| Criterion | Minimum for CRAN | Minimum for JOSS |
|-----------|-----------------|-----------------|
| License | OSI-approved | OSI-approved |
| Tests | Pass R CMD check | Automated test suite |
| Docs | Man pages for exports | README + examples + API docs |
| History | Any | 6+ months public |
| Users | Not required | Evidence of use encouraged |
| Paper | Not required | 750-1750 word paper.md |

### Timeline Expectations

| Stage | Duration |
|-------|----------|
| CRAN prep + audit | 1-3 days |
| CRAN review | 1-7 days (usually 1-2) |
| JOSS prep + paper | 1-2 days |
| JOSS review | 2-8 weeks |
| JSS prep + paper | 2-4 weeks |
| JSS review | 6-18 months |

## Reference Files

- **`${CLAUDE_PLUGIN_ROOT}/docs/cran-reference.md`** — CRAN Repository Policy, submission workflow, common rejections
- **`${CLAUDE_PLUGIN_ROOT}/docs/