joss-draft

name	joss-draft
description	This skill should be used when the user asks to "draft a JOSS paper", "write paper.md", "create JOSS paper", "write JOSS submission", "draft paper.md for JOSS", or mentions writing a JOSS software paper. It analyzes an R package and drafts a complete paper.md and paper.bib following JOSS format requirements and patterns from successful R package papers.

JOSS Paper Drafting

Analyze an R package and draft a complete paper.md and paper.bib for JOSS submission. The paper follows current JOSS format requirements (2025+) with all required sections.

Workflow

1. Analyze the Package

Before writing, thoroughly understand what the package does.

Read core files (Read tool):

• DESCRIPTION — title, description, author info, dependencies
• README.md or README.Rmd — overview, examples, installation
• CLAUDE.md — architecture and design decisions (if present)
• NEWS.md — development history and features
• CITATION.cff or inst/CITATION — existing citation metadata

Understand the API (Glob/Grep/Read tools):

• List all exported functions from NAMESPACE
• Read key R source files to understand architecture
• Identify the core abstraction (e.g., the main class/object)
• Note the design pattern (closure-returning, S3/S4/R6, functional)

Check vignettes (Glob/Read tools):

• Read all vignettes for use cases and examples
• Identify the strongest example for the paper

Identify the research context:

• What domain does this serve? (survival analysis, Bayesian stats, etc.)
• What problem does it solve that existing tools don't?
• Who is the target audience? (researchers, practitioners, students)

2. Get Author Metadata

Load user config (Read tool): Read .claude/pub-pipeline.local.md if it exists. Extract author and coauthors fields from the YAML frontmatter to populate the paper's author list.

If the config file is missing or incomplete, ask the user for:

• Full name, ORCID, affiliation, email for each author
• Any additional co-authors

If the user has the deets CLI installed, it can also be used as an optional fallback:

deets get identity.name
deets get academic.orcid

3. Identify Competing Packages

Search for competing/related R packages. Name specific packages and explain how this package differs:

• What does each competitor do?
• What gap does this package fill?
• Why build new rather than contribute to existing?

How to find competitors (WebSearch/Read/Grep tools):

• Search CRAN Task Views relevant to the package's domain (WebSearch tool)
• Read the package's DESCRIPTION file for packages listed in Imports/Suggests
• Search the package's README and vignettes for mentions of other packages (Grep tool)
• Check the user config's r.competitors field for pre-identified competitors
• Search the web for "[domain] R package" (WebSearch tool)

This is critical — JOSS reviewers specifically check the "State of the Field" section for this.

4. Draft paper.md

Populate the YAML frontmatter from the user config (author, coauthors, affiliations). Use the r.domain and r.audience fields to inform the Statement of Need. Use r.competitors to seed the State of the Field section. Use ai_usage fields for the AI Usage Disclosure section.

Create paper.md following this template structure:

---
title: 'packagename: Short description of what it does'
tags:
  - R
  - [domain tag 1]
  - [domain tag 2]
  - [method tag]
authors:
  - name: First M. Last
    orcid: 0000-0000-0000-0000
    affiliation: 1
affiliations:
  - name: Department, University
    index: 1
date: "DD Month YYYY"
bibliography: paper.bib
---

# Summary

[2-3 paragraphs: What the package does, at a high level, for a
non-specialist audience. Include the core abstraction and key
capabilities. Mention the language (R) and any notable design
choices.]

# Statement of Need

[1-2 paragraphs: What research problem this solves. Who needs it
and why. What is the gap in existing tools. Be specific about the
target audience — researchers in X, practitioners doing Y.]

# State of the Field

[1-2 paragraphs: Name specific competing packages. For each,
state what it does and what it lacks. Explain why building this
package was justified. Use citations for each package mentioned.]

# Software Design

[1-2 paragraphs: Key architectural decisions. The core abstraction
(e.g., closure-returning pattern, S3 class hierarchy). Trade-offs
made (e.g., flexibility vs performance, generality vs specificity).
Integration with other packages.]

# Research Impact Statement

[1 paragraph: Evidence of use. Published analyses, ongoing projects,
adoption by other packages. If the package is new, describe the
near-term credible impact based on the research community it serves.]

# AI Usage Disclosure

[1 paragraph: Transparent disclosure. If AI tools were used in
development, state which tools, where they were applied, and confirm
human oversight of all design decisions. If no AI was used, state
that explicitly.]

# Acknowledgements

[Funding sources, contributors, institutional support.]

# References

Writing guidelines:

• Target 750-1750 words (aim for ~1000)
• Write tight prose — every sentence earns its place
• No hyperbole or unjustified superlatives
• Use active voice where it improves clarity
• Match the author's existing voice from README/vignettes
• Include 1-2 inline code examples if they clarify the design
• Use [@key] for parenthetical citations, @key for in-text

5. Draft paper.bib

Create paper.bib with BibTeX entries for:

• The R language itself (@r_core)
• All packages named in State of the Field
• Key methodology references
• Any references from the package's existing CITATION or vignettes

Use standard BibTeX format:

@Manual{r_core,
  title = {R: A Language and Environment for Statistical Computing},
  author = {{R Core Team}},
  organization = {R Foundation for Statistical Computing},
  address = {Vienna, Austria},
  year = {YYYY},  % use the current year
  url = {https://www.R-project.org/},
}

@Article{package_key,
  title = {Package Title},
  author = {Author Name},
  journal = {Journal Name},
  year = {2023},
  doi = {10.xxxx/xxxxx},
}

6. Validate the Draft

After writing, check:

• Word count is 750-1750
• All @key citations have matching BibTeX entries
• All required sections present (Summary, Statement of Need, State of the Field, Software Design, Research Impact, AI Disclosure)
• YAML frontmatter has all required fields
• Date format is correct (%e %B %Y)
• Referenced figure files exist (if any)

7. Place Files

Place paper.md and paper.bib at the package root or in a paper/ subdirectory. Ask the user which location they prefer.

Reference Files

For JOSS format specifications and exemplar papers, consult:

• ${CLAUDE_PLUGIN_ROOT}/docs/joss-reference.md — Complete JOSS paper format spec, YAML fields, citation syntax, math/figure syntax
• ${CLAUDE_PLUGIN_ROOT}/docs/joss-exemplars.md — Real JOSS R package papers with full content, structural analysis, patterns and anti-patterns

Delegation

For substantial prose writing, consider delegating to the academic-paper-writer agent (if available) with format set to "Markdown (JOSS)". Provide the agent with the package analysis from steps 1-3 as context.

For critical review of the draft, use the academic-paper-reviewer agent (if available) with JOSS format.

Important Notes

• The "State of the Field" section is where most JOSS reviews focus. Name specific packages.
• JOSS papers are short — resist the urge to write a full methods paper. Save that for JSS.
• Code examples in the paper should be minimal and illustrative, not comprehensive.
• ORCID is required for all authors. Help users register at https://orcid.org if needed.
• The paper must be stored in the same git repository as the software.