paper-plan

name: paper-plan description: Produces a detailed, venue-aware paper outline from all available upstream artifacts (RESEARCH_PLAN, lit review, idea report, refined proposal, experiment plan/results, narrative report). Creates section-by-section plan with word budgets, claim-evidence matrix, figure/table plan, and citation scaffolding. Uses journal templates from templates/ for venue-specific formatting. argument-hint: [topic-or-narrative-doc] tools: Bash(*), Read, Write, Edit, Grep, Glob, Agent, WebSearch, WebFetch, mcp__codex__codex, mcp__codex__codex-reply

Skill: paper-plan

You produce a concrete, actionable paper outline before any writing begins from: $ARGUMENTS

Constants

• REVIEWER_MODEL = gpt-5.4 — Model used via Codex MCP for outline review. Must be an OpenAI model.
• TARGET_VENUE = IJGIS — Default venue. User can override (e.g., /paper-plan "topic" — venue: AAAG). Supported: TGIS, RSE, ISPRS_JPRS, AAG_ANNALS, IEEE_TGRS, ICML, ICLR, NeurIPS, CVPR, ACL, AAAI, ACM, IEEE_JOURNAL (IEEE Transactions / Letters), IEEE_CONF (IEEE conferences).
• MAX_PAGES = 40 — Adjust based on paper template selected. ML conferences typically 8–10 pages (excluding refs/appendix). IEEE venues include references in page count.
• MAX_PRIMARY_CLAIMS = 2 — One dominant contribution + one supporting. Prevents scope creep.
• MAX_FIGURES = 8 — Soft cap; hero figure + up to 7 supporting figures/tables.
• OUTPUT_PATH = output/PAPER_PLAN.md

Orchestra-Guided Writing Overlay

Keep the existing workflow and outputs, but use the shared references below to improve the quality of the story and outline.

• Read skills/knowledge/academic-writing.md when framing the one-sentence contribution, Abstract, Introduction, Related Work, or hero figure.
• Read skills/knowledge/geoai-domain.md for GIScience/GeoAI framing conventions.
• Read skills/knowledge/spatial-methods.md when planning methodology sections for spatial analysis papers.
• Only load these references when needed; do not paste their full contents into the working draft.

Phase 0: Load Checkpoint (Resume Support)

Check for existing state:

1. Read output/PAPER_PLAN.md — if it exists and was generated in the current session, ask the user whether to rebuild or refine it.
2. Read handoff.json — if pipeline.stage indicates paper-plan is in progress, resume from the last recorded phase.

If no checkpoint exists, proceed to Phase 1.

Phase 1: Gather Context

Read all available upstream artifacts. Each file is optional — missing files are soft failures. Record which files were found and which were missing; this information goes into the plan's "Input Files Used" and "Missing Inputs" sections.

Primary Inputs (read in this order)

Context Synthesis Rules

1. NARRATIVE_REPORT.md is king — if it exists, it is the primary planning source. It was specifically designed to consolidate all upstream artifacts for the paper-writing pipeline. Use other files only to fill gaps or verify claims.
2. RESEARCH_PLAN.md is the research intent — it defines what the researcher wants to achieve. FINAL_PROPOSAL.md is the refined version. EXPERIMENT_RESULT.md is what actually happened. The outline must reconcile all three.
3. Never fabricate from gaps — if a file is missing, the outline must explicitly mark the affected sections as [NEEDS: <missing-file>] rather than inventing content.
4. Numbers are sacred — copy metrics verbatim from EXPERIMENT_RESULT.md and APPROVED_CLAIMS.md. Never round, paraphrase, or extrapolate.

Phase 2: Determine Venue and Paper Type

Step 2.1: Resolve TARGET_VENUE

Check in this order (first match wins):

1. Explicit user argument (e.g., — venue: ISPRS_JPRS)
2. RESEARCH_PLAN.md target venue field
3. NARRATIVE_REPORT.md venue target section
4. output/PAPER_PLAN.md existing venue (if refining)
5. Default: IJGIS

Step 2.2: Load Venue Template

Based on TARGET_VENUE, choose the appropriate template from templates/:

If the template does not exist locally, use WebSearch to retrieve the venue's author guidelines and page limits.

Step 2.3: Determine Paper Type

Infer from the contributions and method:

Step 2.4: Set Page Budget

Derive from venue:

Phase 3: Build the Outline

Write output/PAPER_PLAN.md following the structure in templates/PAPER_PLAN_TEMPLATE.md (Sections §0–§26). The template is the target schema; fill every section with content derived from the upstream artifacts.

Section-by-Section Generation Rules

§0 Document Status — Fill version, date, venue, manuscript type, readiness level, list of input files consumed and missing.

§1 One-Paragraph Summary — Synthesize from NARRATIVE_REPORT.md §1 or FINAL_PROPOSAL.md contributions. The one-sentence claim must be specific, defensible, and evidence-based. Draft a 150–250 word abstract-style summary.

§2 Target Journal Strategy — Use venue template to fill journal fit, audience, expectations. Read skills/knowledge/academic-writing.md for framing advice.

§3 Research Context and Motivation — Draw from LIT_REVIEW_REPORT.md synthesis + RESEARCH_PLAN.md problem statement. Quantify the problem scale.

§4 Research Gap — Extract directly from LIT_REVIEW_REPORT.md Gap Analysis section. List specific gaps with boundary citations. Explain why existing work is insufficient.

§5 Novelty and Contributions — Numbered contributions from FINAL_PROPOSAL.md or NARRATIVE_REPORT.md. Each contribution tied to a specific experiment/claim. Include "What This Paper Is Not Claiming" to set expectations.

§6 Research Questions and Hypotheses — From RESEARCH_PLAN.md or FINAL_PROPOSAL.md. Align RQs with experiment design from EXPERIMENT_PLAN.md.

§7 Study Scope and Boundaries — Spatial, temporal, data, and method scope. Explicit limitations of scope.

§8 Data and Materials — From DATA_MANIFEST.md and EXPERIMENT_PLAN.md. For each dataset: source, resolution, temporal coverage, preprocessing, license.

§9 Methodological Plan — From FINAL_PROPOSAL.md method description and EXPERIMENT_PLAN.md design. Include baselines, evaluation protocol, spatial analysis components. Read skills/knowledge/spatial-methods.md for GIScience method framing.

§10 Experiments — From EXPERIMENT_PLAN.md (design) and EXPERIMENT_RESULT.md (outcomes). Mark incomplete experiments as [PENDING].

§11 Results Summary — From EXPERIMENT_RESULT.md and APPROVED_CLAIMS.md. Headline findings in priority order. Quantitative results with exact values. Flag missing results as [NEEDS: experiment completion].

§12 Claim-to-Evidence Map — The backbone of the plan. Every major claim maps to: evidence source, quantitative support, figure/table ID, experiment ID, confidence level. Unsupported claims go into "Unsupported or Weak Claims" subsection.

§13 Figures Plan — From NARRATIVE_REPORT.md figure plan or EXPERIMENT_RESULT.md outputs. For each figure: ID, type, description, data source, status, priority.

CRITICAL: Hero Figure (Fig. 1) — Describe in detail:

• What methods/concepts are being compared
• What the visual difference should demonstrate
• Caption draft that clearly states the comparison
• Why a skim reader understands the paper from this figure alone

§14 Tables Plan — Required tables: dataset summary, baseline comparison, ablation (if applicable), hyperparameters, error analysis.

§15 Related Work Synthesis — From LIT_REVIEW_REPORT.md thematic synthesis. Group into 3–4 clusters that map to the paper's related work section. For each cluster: summary, representative studies, how our work relates and differs.

§16 Discussion Plan — Interpretation themes, implications (GIScience/GeoAI + practical), responsible research considerations, generalizability.

§17 Limitations and Future Work — Concrete limitations from EXPERIMENT_RESULT.md and AUTO_REVIEW_REPORT.md. Severity assessment. 3–5 specific future work directions.

§18 Reproducibility and Open Science Plan — Code availability, data availability, reproducibility assets checklist.

§19 Manuscript Structure Plan — Section outline (5–8 sections, flexible) with word budgets. Per-section: goal, key points, gap statement, contributions paragraph.

§20 Abstract Blueprint — Sentence-by-sentence abstract structure: background → gap → method → data → main results → significance.

§21 Title and Framing Options — 3 candidate titles. Dominant framing (methodological / applied / benchmark / conceptual).

§22 Citation and Evidence Bank — Per-section citation plan from LIT_REVIEW_REPORT.md verified citations. Flag unverified citations with [VERIFY].

§23 Writing Instructions for Downstream Agent — Non-negotiable writing goals, style instructions, section priorities, writing risks to avoid. Venue-specific tone guidance.

§24 Open Issues Before Drafting — Critical gaps, nice-to-have improvements, required follow-up actions with owners and priorities.

§25 Final Readiness Assessment — Ready for full/partial/skeleton draft? Minimum conditions for drafting. Recommended drafting strategy.

§26 Executive Summary for Manuscript Writer — Concise: what the paper is about, why publishable, strongest/weakest evidence, what to emphasize, what to be careful about.

Section Count and Word Budget

IMPORTANT: The section count is FLEXIBLE (5–8 sections). Choose what fits the content and paper type best. The template sections above are the planning schema — the actual manuscript sections in §19 are determined by venue and paper type.

Example word budgets for a 25-page IJGIS paper (~8000 words):

Adjust proportions for ML conferences (heavier methods/experiments, lighter lit review) or applied papers (heavier study area/discussion).

Phase 4: Figure and Table Plan

Consolidate the figure and table plan from §13 and §14 into a single reference table:

## Figure & Table Plan

| ID | Type | Description | Data Source | Priority | Status |
|----|------|-------------|-------------|----------|--------|
| Fig 1 | Hero/Architecture | System overview or key comparison | manual/code | HIGH | [Ready/Needed] |
| Fig 2 | Map | Study area with spatial units | GIS data | HIGH | [Ready/Needed] |
| Fig 3 | Line/Bar plot | Main quantitative comparison | output/EXPERIMENT_RESULT.md | HIGH | [Ready/Needed] |
| Fig 4 | Heatmap/Map | Spatial pattern visualization | spatial-analysis/ | MEDIUM | [Ready/Needed] |
| Table 1 | Data summary | Dataset characteristics | DATA_MANIFEST.md | HIGH | [Ready/Needed] |
| Table 2 | Comparison | Main results vs. baselines | EXPERIMENT_RESULT.md | HIGH | [Ready/Needed] |
| Table 3 | Ablation | Component contribution analysis | EXPERIMENT_RESULT.md | MEDIUM | [Ready/Needed] |

For each HIGH-priority figure, provide:

• Detailed visual specification (axes, colors, annotations)
• Caption draft
• Data source path
• Generation method (Python script / manual / architecture diagram prompt)

Check output/figures/FIGURE_MANIFEST.md — if figures already exist from a prior paper-figure-generate run, reference them rather than re-planning.

Phase 5: Citation Scaffolding

For each section, list required citations drawn from verified sources:

## Citation Plan
- §Intro: [paper1], [paper2], [paper3] (problem motivation)
- §Related: [paper4]-[paper10] (categorized by cluster from §15)
- §Method: [paper11] (baseline), [paper12] (technique we build on)
- §Discussion: [paper13] (comparison point), [paper14] (implication support)

Citation rules:

1. NEVER generate BibTeX from memory — always verify via search or existing .bib files
2. Every citation must be verified: correct authors, year, venue
3. Flag any citation you are unsure about with [VERIFY]
4. Prefer published versions over arXiv preprints when available
5. Draw primarily from output/LIT_REVIEW_REPORT.md which has already-verified citations
6. For missing citations, use WebSearch to find the correct reference — do not guess

Phase 6: Cross-Review with REVIEWER_MODEL

Send the complete outline to REVIEWER_MODEL for feedback:

mcp__codex__codex:
  model: gpt-5.4
  config: {"model_reasoning_effort": "xhigh"}
  prompt: |
    Review this paper outline for a [VENUE] submission.
    [full outline including Claims-Evidence Matrix]

    Score 1-10 on:
    1. Logical flow — does the story build naturally?
    2. Claim-evidence alignment — every claim backed?
    3. Missing experiments or analysis
    4. Positioning relative to prior work
    5. Page budget feasibility (MAX_PAGES = main body to Conclusion end, excluding refs/appendix for most venues; IEEE venues include refs)
    6. Front-matter strength — are the abstract, introduction, and hero figure plan strong enough for skim-reading reviewers?
    7. Input coverage — does the plan utilize all available upstream artifacts?
    8. Venue fit — does the framing, depth, and emphasis match the target journal's expectations?

    For each weakness, suggest the MINIMUM fix.
    Be specific and actionable — "add X" not "consider more experiments".

If Codex MCP is not available, spawn a subagent with fresh context to review the outline instead.

Apply feedback before finalizing. If any score is below 6, address the specific weakness before proceeding.

Phase 7: Self-Check

Before saving, verify all of the following:

• Every numbered contribution maps to ≥1 row in the Claims-Evidence Matrix (§12)
• Every claim in the matrix has a source file path (e.g., EXPERIMENT_RESULT.md §3.2)
• Every HIGH-priority figure has a detailed visual specification and caption draft
• Hero figure description is detailed enough for paper-figure-generate to produce it
• Missing upstream files are documented in §0 "Missing Inputs" and affected sections are marked [NEEDS: <file>]
• Word budgets sum to within ±10% of venue word limit
• Venue-specific formatting norms are noted (citation style, page counting, appendix rules)
• No fabricated claims, numbers, or citations exist in the plan
• §25 readiness assessment accurately reflects the state of available evidence
• §26 executive summary is actionable for paper-draft

If any check fails, fix the plan before writing the final output.

Phase 8: Output

Save the final outline to output/PAPER_PLAN.md.

Append a one-line entry to output/PROJ_NOTES.md:

[YYYY-MM-DD] paper-plan: PAPER_PLAN.md built from [list of consumed input files] — [N] sections, [M] figures, [K] claims, venue=[VENUE]

Report back to the user:

Paper plan complete:
- Title: [proposed title]
- Venue: [TARGET_VENUE] | Page limit: [MAX_PAGES]
- Sections: [N] ([list names])
- Contributions: [N]
- Claims in evidence matrix: [M] (supported: X, pending: Y)
- Figures planned: [total] (hero: 1, auto: X, manual: Y)
- Tables planned: [Z]
- Input files consumed: [list]
- Missing inputs: [list or "none"]
- Readiness: [full draft / partial draft / skeleton — from §25]

Ready to invoke /paper-figure-generate or /paper-draft.

Key Rules

• Large file handling: If the Write tool fails due to file size, immediately retry using Bash (cat << 'EOF' > file) to write in chunks. Do NOT ask the user for permission — just do it silently.
• Do NOT generate author information — leave author block as placeholder or anonymous.
• Be honest about evidence gaps — mark claims as [NEEDS: evidence] rather than overclaiming. The downstream paper-draft skill will handle these appropriately.
• Page budget is hard — if content exceeds MAX_PAGES, suggest what to move to appendix.
• MAX_PAGES counting differs by venue — ML conferences: main body to Conclusion end, references/appendix NOT counted. IEEE venues: references ARE counted toward the page limit.
• Venue-specific norms — ML conferences (ICLR/NeurIPS/ICML) use natbib (\citep/\citet); IEEE venues use cite package (\cite{}, numeric style); GIScience journals typically use author-year (APA or similar).
• Claims-Evidence Matrix is the backbone — every claim must map to evidence, every experiment must support a claim. This matrix is the primary contract between paper-plan and paper-draft.
• Front-load the story — the outline should make the contribution clear in the title, abstract blueprint, introduction plan, and hero figure before the reader reaches the full method.
• Figures need detailed descriptions — especially the hero figure, which must clearly specify comparisons and visual expectations.
• Section count is flexible — 5–8 sections depending on paper type. Don't force content into a rigid template.
• NARRATIVE_REPORT.md is the richest source — if it exists, use it as the primary input and cross-reference other files for verification.
• Template is the target schema — follow templates/PAPER_PLAN_TEMPLATE.md (§0–§26) as the output structure. Every section should be filled or explicitly marked N/A with a reason.
• Do NOT generate BibTeX — citation scaffolding provides keys and context, but actual BibTeX generation belongs to downstream skills.

Composability

Upstream Skills (produce inputs for this skill)

Downstream Skills (consume this skill's output)

Pipeline Context

When invoked as part of paper-writing-pipeline, this skill is Phase 1. The pipeline expects output/PAPER_PLAN.md to exist after this skill completes.

When invoked standalone, ensure at least one of RESEARCH_PLAN.md, FINAL_PROPOSAL.md, or NARRATIVE_REPORT.md exists — otherwise the skill has insufficient context to build a meaningful plan.

Acknowledgements

Outline methodology inspired by Research-Paper-Writing-Skills (claim-evidence mapping), claude-scholar (citation verification), and Imbad0202/academic-research-skills (claim verification protocol). Template structure follows the §0–§26 schema from templates/PAPER_PLAN_TEMPLATE.md.