Paper Writer

Workflow

Phase 0: Project Initialization

When the user invokes this skill, ask for:

1. Working title (can change later)
2. Paper type (Original Article / Case Report / Review / Letter / Systematic Review)
3. Target journal (optional but recommended)
4. Language (English / Japanese / Both)
5. Research question in one sentence
6. Key data available (what Tables/Figures already exist?)

Step 0.1: Capture Journal Requirements

If a target journal is specified, look up and document:

• Word limits: total manuscript, abstract, each section (if specified)
• Citation style: Vancouver, APA, NLM, or other
• Required sections: some journals require separate Conclusion, others don't
• Abstract format: structured or unstructured, word limit
• Figure/Table limits: maximum number allowed
• Reporting guideline: which checklist the journal requires
• Special requirements: cover page format, line numbering, etc.
• AI disclosure: whether the journal requires AI usage disclosure, and where (Methods, Acknowledgments, or dedicated section). See references/ai-disclosure.md.
• Keywords: number required, MeSH preferred or free-text. See references/keywords-guide.md.
• Graphical abstract: required or optional. See templates/graphical-abstract.md.

Use WebSearch to look up the journal's "Instructions for Authors" page.

Record all requirements in the README.md under a "Journal Requirements" section.

Step 0.2: Select Reporting Guideline

Based on paper type and study design, select the appropriate reporting guideline:

Read ~/.claude/skills/paper-writer/references/reporting-guidelines.md (summary) or references/reporting-guidelines-full.md (comprehensive) and note the key checklist items for the selected guideline. These items will be checked throughout the writing process.

Step 0.3: Create Project Directory

For Original Article / Review / Letter / Systematic Review:

{project-dir}/
├── README.md                        # Project dashboard (status, timeline, links)
│
├── 00_literature/                   # Phase 1: Literature
│   ├── search-strategy.md           #   Search terms, databases, dates
│   ├── literature-matrix.md         #   Structured comparison table
│   └── key-papers/                  #   Notes on important papers (1 file per paper)
│
├── 01_outline.md                    # Phase 2: Paper skeleton
│
├── sections/                        # Phase 3: Manuscript sections (writing order)
│   ├── 02_methods.md
│   ├── 03_results.md
│   ├── 04_introduction.md
│   ├── 05_discussion.md
│   ├── 06_conclusion.md
│   ├── 07_abstract.md
│   └── 08_title.md
│
├── tables/                          # Tables (numbered: table1_baseline.md, ...)
├── figures/                         # Figures + captions (fig1_caption.md, ...)
├── supplements/                     # Supplementary materials
│   ├── supplementary-tables/        #   e.g., tableS1_sensitivity.md
│   ├── supplementary-figures/       #   e.g., figS1_subgroup.md
│   └── appendices/                  #   Additional methods, datasets, etc.
│
├── data/                            # Research data (see templates/data-management.md)
│   ├── raw/                         #   Original data (READ-ONLY, gitignored)
│   ├── processed/                   #   Cleaned, de-identified data
│   ├── analysis/                    #   Statistical output, scripts
│   └── data-dictionary.md           #   Variable definitions
│
├── ethics/                          # Ethics & regulatory
│   ├── irb-approval.md              #   IRB approval details, number, dates
│   ├── informed-consent.md          #   Consent process documentation
│   ├── protocol.md                  #   Study protocol (SPIRIT if applicable)
│   └── registration.md              #   Trial/study registration (UMIN, ClinicalTrials.gov)
│
├── submissions/                     # Submission history (1 subfolder per attempt)
│   └── v1_{journal}/                #   e.g., v1_bmj/
│       ├── compiled-manuscript.md   #     Full compiled manuscript snapshot
│       ├── cover-letter.md          #     Cover letter
│       ├── title-page.md            #     Title page
│       ├── declarations.md          #     Ethics, COI, funding, AI disclosure
│       ├── highlights.md            #     Key points (if required)
│       ├── graphical-abstract.md    #     Graphical abstract (if required)
│       └── submission-log.md        #     Date, portal, manuscript #, status
│
├── revisions/                       # Revision rounds (Phase 8)
│   └── r1/                          #   Round 1
│       ├── reviewer-comments.md     #     Original reviewer comments
│       ├── response-letter.md       #     Point-by-point response
│       ├── revision-cover-letter.md #     Revision cover letter
│       ├── diff-summary.md          #     Changes made (section, line, change)
│       └── compiled-manuscript.md   #     Revised manuscript snapshot
│
├── coauthor-review/                 # Co-author feedback tracking
│   ├── review-tracker.md            #   Who reviewed, when, status
│   └── feedback/                    #   Individual feedback files
│
├── correspondence/                  # Editor & reviewer communication log
│   └── YYYY-MM-DD_{subject}.md      #   e.g., 2026-03-05_decision-letter.md
│
├── references/                      # Reference management
│   └── 09_references.md             #   Formatted reference list
│
├── checklists/                      # Quality control
│   ├── section-quality.md           #   Per-section quality scores
│   ├── submission-ready.md          #   Pre-submission checklist
│   ├── reporting-guideline.md       #   CONSORT/STROBE/etc. item tracking
│   ├── gate-state.md                #   Stage-gate iteration state
│   └── feedback-*.md                #   Auto-generated gate feedback
│
└── log/                             # Decision & progress log
    ├── decisions.md                 #   Key decisions with rationale
    ├── meetings.md                  #   Meeting notes (co-authors, supervisor)
    └── timeline.md                  #   Milestone targets & actual dates

For Case Report:

{project-dir}/
├── README.md                        # Project dashboard
│
├── 00_literature/
│   ├── search-strategy.md
│   ├── literature-matrix.md
│   └── key-papers/
│
├── 01_outline.md
│
├── sections/
│   ├── 02_case.md                   # Case presentation (CARE structure)
│   ├── 03_introduction.md           # Introduction (why reportable)
│   ├── 04_discussion.md
│   ├── 05_abstract.md               # Abstract (CARE format)
│   └── 06_title.md                  # Title (must contain "case report")
│
├── tables/
├── figures/
├── supplements/
│   ├── supplementary-tables/
│   ├── supplementary-figures/
│   └── appendices/
│
├── data/
│   ├── raw/
│   ├── processed/
│   ├── analysis/
│   └── data-dictionary.md
│
├── ethics/
│   ├── irb-approval.md
│   ├── informed-consent.md          # Patient consent for publication
│   └── patient-perspective.md       # Patient's perspective (CARE item)
│
├── submissions/
│   └── v1_{journal}/
│       ├── compiled-manuscript.md
│       ├── cover-letter.md
│       ├── title-page.md
│       ├── declarations.md
│       └── submission-log.md
│
├── revisions/
│   └── r1/
│       ├── reviewer-comments.md
│       ├── response-letter.md
│       ├── diff-summary.md
│       └── compiled-manuscript.md
│
├── coauthor-review/
│   ├── review-tracker.md
│   └── feedback/
│
├── correspondence/
│   └── YYYY-MM-DD_{subject}.md
│
├── references/
│   └── 07_references.md
│
├── checklists/
│   ├── section-quality.md
│   ├── submission-ready.md
│   ├── reporting-guideline.md
│   ├── gate-state.md
│   └── feedback-*.md
│
└── log/
    ├── decisions.md
    ├── meetings.md
    └── timeline.md

Read ~/.claude/skills/paper-writer/templates/project-init.md with the Read tool and use it to generate README.md. For Case Reports, use project-init-case.md instead.

File numbering follows the recommended writing order, not the reading order. This is intentional.

Step 0.4: Organize Research Data

If the user has existing research data (clinical records, CSV files, statistical output, etc.):

1. Create data/raw/, data/processed/, data/analysis/ directories
2. Read ~/.claude/skills/paper-writer/templates/data-management.md for the full template
3. Ask the user to place raw data files in data/raw/ — these files are READ-ONLY from this point
4. Create data/raw/README.md documenting the data source, extraction date, and IRB information
5. Create data/data-dictionary.md listing all variables with types, ranges, and labels
6. Confirm de-identification status — if not yet de-identified, create a processing plan in data/processed/README.md

Security rules:

• NEVER commit patient-identifiable data to git
• Add data/raw/*.csv, data/raw/*.xlsx etc. to .gitignore if the repository is shared
• Always confirm IRB approval number before proceeding with data analysis

Data flow: raw/ (never modify) → processed/ (clean, de-identify) → analysis/ (statistical output) → tables/ and figures/ (manuscript-ready)

Step 0.5: Data Analysis

If the user has quantitative data ready for analysis, Claude Code can execute Python scripts directly. Read ~/.claude/skills/paper-writer/templates/analysis-workflow.md for the full workflow.

Available analysis scripts:

Workflow:

1. Inspect data: Load data/processed/cohort_final.csv, check shape, dtypes, missing values
2. Table 1: Run scripts/table1.py to generate baseline characteristics table → tables/table1.md
3. Primary analysis: Choose analysis type based on study design:
   • Cross-sectional / case-control → logistic regression (OR with 95% CI)
   • Cohort with time-to-event → survival analysis (Kaplan-Meier, log-rank)
   • Continuous outcome → linear regression
   • Group comparison → t-test / Mann-Whitney U
4. Subgroup & sensitivity analyses: By sex, age group, disease severity, etc.
5. Generate figures: Box plots, KM curves, forest plots, ROC curves
6. Link to manuscript: Map analysis output to Results section paragraphs

Analysis output directory: All results go to data/analysis/. Figures for the manuscript go to figures/.

Required Python packages: numpy, pandas, scipy, statsmodels, lifelines, matplotlib, seaborn

pip install numpy pandas scipy statsmodels lifelines matplotlib seaborn scikit-learn

Statistical reporting requirements (before writing Results):

• Effect sizes with 95% confidence intervals
• P values to 3 decimal places (P < 0.001 for very small)
• Statistical test names specified
• Software and version documented
• Two-sided tests (unless justified)
• Multiple comparison correction (if >1 primary outcome)
• Missing data handling described

See references/statistical-reporting-full.md for detailed SAMPL guidelines and templates/analysis-workflow.md for step-by-step commands.

Phase 1: Literature Search & Organization

Step 1.1: Define Search Strategy

Create 00_literature/search-strategy.md with:

• Databases: PubMed, Google Scholar (always available); Scopus, CiNii (if user has institutional access)
• Search terms: MeSH terms + free-text keywords
• Inclusion/exclusion criteria for papers
• Date range

How to search:

Use WebSearch with targeted queries:

• For PubMed: search "search terms" pediatric asthma pubmed
• For Google Scholar: search "search terms" site:scholar.google.com
• For general: search the research question directly

If WebSearch results are limited, use WebFetch on specific PubMed URLs: