grind-lab-core/night_owl_research_agent/paper-draft

Skill: paper-draft

You turn the plan in `output/PAPER_PLAN.md` into a journal-quality manuscript draft for: $ARGUMENTS

This skill is the drafting counterpart to paper-plan and paper-figure-generate. It produces Markdown manuscript files in output/manuscript/ that downstream skills (paper-write, paper-convert, paper-review-loop) can consume for LaTeX conversion, review, and polish. When invoked inside paper-writing-pipeline, this skill is Phase 3's content generator — it writes the prose, not the LaTeX scaffolding.

The skill supports the full GIScience / GeoAI / remote sensing manuscript spectrum:

• methodological innovation papers
• system / platform / autonomous-agent papers
• benchmark and evaluation papers
• applied case-study papers
• conceptual / framework papers
• multimodal GeoAI papers
• remote sensing analysis papers
• GIScience theory + method papers

Constants

• PLAN_PATH = `output/PAPER_PLAN.md` — source of truth for manuscript intent.
• MS_DIR = `output/manuscript/` — all draft artifacts go here.
• MAIN_DRAFT = `output/manuscript/MANUSCRIPT_DRAFT.md` — integrated manuscript.
• SECTIONS_DIR = `output/manuscript/sections/` — per-section drafts.
• TARGET_VENUE — read from PAPER_PLAN.md header, else research_contract.md, else default IJGIS.
• PAPER_TYPE — read from PAPER_PLAN.md §21 framing, else infer from contributions in §5.
• LIT_REVIEW_REPORT = `output/LIT_REVIEW_REPORT.md` — consolidated literature review; Synthesis and Gap Analysis sections ground Related Work and gap framing.
• FIGURE_MANIFEST = `output/figures/FIGURE_MANIFEST.md` — figures that actually exist.
• FIGURE_CAPTIONS = `output/figures/FIGURE_CAPTIONS.md` — manuscript-ready captions.
• REVIEWER_MODEL = `gpt-5.4` — used via Codex MCP for section-level critique (optional).
• DRAFT_MODE — one of full, partial, skeleton. Decided in Phase 2 from readiness signals; may be forced by argument. Default option is full.

Override inline: /paper-draft all — venue: ISPRS, mode: partial.

Core Philosophy

1. Evidence over eloquence. Every non-trivial claim must trace to APPROVED_CLAIMS.md, an experiment result file, a literature synthesis, or the PAPER_PLAN.md claim-to-evidence map. If a claim cannot be traced, it is softened, marked [NEEDS EVIDENCE], or cut.
2. Plan is intent, referenced files are truth. PAPER_PLAN.md says what the paper wants to argue. The referenced experiment logs, synthesis notes, and figure manifests say what the project can actually support. Draft against the intersection.
3. Readiness-aware drafting. The skill produces a full, partial, or skeleton manuscript — never a polished-looking draft that silently papers over missing results.
4. Journal voice is non-negotiable. IJGIS, ISPRS JPRS, RSE, and TGIS reviewers expect formal, precise, rigor-first prose. No hype, no startup-style framing, no "revolutionary."
5. Terminology discipline. Model names, dataset names, system names, metric names, experiment labels, and geographic names are fixed at first use and never drift across sections.
6. Generator-evaluator separation. This skill writes. Section scoring and adversarial review happen in auto-review-loop / paper-review-loop, not here.

Inputs

Primary

• `output/PAPER_PLAN.md` — required. The manuscript orchestration artifact (see templates/PAPER_PLAN_TEMPLATE.md for the expected §0–§26 structure).

Secondary (read on demand when the plan references them, or when specificity demands it)

• research_contract.md — active idea, problem, method, success criteria.
• memory/APPROVED_CLAIMS.md — the only source of verified numerical / empirical claims.
• output/LIT_REVIEW_REPORT.md — consolidated literature review (Findings, Synthesis by theme, ranked Gap Analysis).
• memory/paper-cache/*.json — per-paper bibliographic + finding records.
• output/EXPERIMENT_LOG.md — full experiment record.
• output/EXPERIMENT_PLAN.md — experiment roadmap, baselines, metrics.
• output/PROJ_NOTES.md — compact one-line discovery log.
• output/spatial-analysis/ — ESDA outputs, diagnostics, interpretation notes.
• output/figures/FIGURE_MANIFEST.md, output/figures/FIGURE_CAPTIONS.md — which figures exist, with captions.
• output/AUTO_REVIEW.md — prior reviewer feedback to incorporate.
• templates/giscience/ · templates/remote_sensing/ · templates/geoscience/ — venue style guides.
• skills/knowledge/academic-writing.md · skills/knowledge/apa-citations.md · skills/knowledge/spatial-methods.md · skills/knowledge/geoai-domain.md — domain and style references.
• skills/shared-references/writing-principles.md · skills/shared-references/venue-checklists.md — load only when drafting Abstract, Introduction, Related Work, or finalizing a venue pass.

Argument forms

• all — draft the full manuscript.
• abstract · introduction · related-work · data · methods · experiments · results · discussion · limitations · conclusion — draft a single section.
• A path to an alternative plan file — use instead of PLAN_PATH.

Outputs

All outputs live under output/manuscript/:

File-naming convention:

• Section files use two-digit zero-padded prefixes in manuscript order (01_, 02_, ...).
• Revisions of a section are saved over the same path; prior versions are preserved in git, not in filename suffixes.
• A v suffix (MANUSCRIPT_DRAFT_v2.md) is used only when the user explicitly requests side-by-side versions.

Workflow

Phase 1 — Read and interpret PAPER_PLAN.md

Read the full plan. Extract, at minimum:

• §0 Document Status → plan version, target journal, manuscript type, readiness level.
• §1 Paper summary → working title, one-sentence claim, short abstract, keywords.
• §2 Journal strategy → audience, tone expectations, rigor / application emphasis.
• §3–§4 Motivation + Gap → the story arc for Introduction.
• §5 Novelty and contributions → contribution list and contribution types (methodological / system / benchmark / applied / conceptual).
• §6 Research questions and hypotheses.
• §7–§8 Scope, data, materials → Data / Study Area section.
• §9 Methodological plan → Methods section spine.
• §10 Experiments + §11 Results → Experiments and Results sections.
• §12 Claim-to-evidence map → the backbone this skill enforces.
• §13–§14 Figures and tables plan.
• §15 Related work synthesis.
• §16 Discussion plan.
• §17 Limitations and future work.
• §18 Reproducibility plan.
• §19 Manuscript structure plan → the authoritative section list for this paper.
• §20 Abstract blueprint.
• §21 Title and framing options → selects PAPER_TYPE.
• §22 Citation and evidence bank.
• §23 Writing instructions for downstream agent → style directives.
• §24 Open issues.
• §25 Readiness assessment → selects DRAFT_MODE.
• §26 Executive summary.

Log missing sections of the plan in COVERAGE_GAPS.md; do not abort.

Phase 2 — Determine DRAFT_MODE

Decision rule (apply top-down, first match wins):

1. `full` — §25 says "Ready for Full Draft: Yes", §12 maps every core claim to existing evidence, §10 has no experiment marked Missing that feeds a core claim, §13 figures are Ready, and §5 contributions are specific.
2. `partial` — ≥60% of the core claims in §12 are supported and figures/tables for the Methods + ≥1 Results subsection exist, but some Results/Discussion content is unsupported.
3. `skeleton` — core experiments incomplete, claim-to-evidence map mostly empty, or readiness marked "No". Produce headings + targeted placeholders + a detailed COVERAGE_GAPS.md.

Record the chosen mode, its justification, and the specific signals that triggered it in DRAFT_README.md.

Phase 3 — Consult referenced project files

For each plan section that will be drafted, pull ground truth from the referenced files before writing. Minimum checks:

• Introduction / Related Work → output/LIT_REVIEW_REPORT.md (Synthesis and Gap Analysis sections), plan §15 and §22.
• Data / Study Area → plan §7–§8, data/DATA_MANIFEST.md if present.
• Methods → plan §9, output/EXPERIMENT_PLAN.md, skills/knowledge/spatial-methods.md.
• Experiments / Results → output/EXPERIMENT_LOG.md, memory/APPROVED_CLAIMS.md, output/spatial-analysis/ reports, output/PROJ_NOTES.md.
• Figures / Tables → output/figures/FIGURE_MANIFEST.md, output/figures/FIGURE_CAPTIONS.md. Never reference a figure ID that is not in the manifest.
• Discussion / Limitations → plan §16–§17, AUTO_REVIEW.md.

If a referenced file is missing, record it in COVERAGE_GAPS.md and either (a) soften the relevant claims, (b) insert a marked placeholder, or (c) drop the sub-claim. Do not guess.

Phase 4 — Select section structure

The default GIScience / remote sensing structure is:

1. Title
2. Abstract + Keywords
3. Introduction
4. Related Work
5. Study Area / Data (merged with Methods for method-heavy papers)
6. Methodology
7. Experimental Design
8. Results
9. Discussion
10. Limitations
11. Conclusion
12. Declarations (data / code availability, ethics) when relevant

Adapt by PAPER_TYPE:

• Methodological innovation — expand Methodology; Related Work clusters around algorithmic lines; add an Ablation subsection in Results.
• System / agent paper — add "System Architecture" section after Methodology; Methods becomes workflow + module decomposition; include a component-ablation subsection; Discussion covers design rationale.
• Benchmark / evaluation — combine Data + Benchmark Design; expand Experimental Design; Results organized by evaluation axis.
• Applied case study — expand Study Area; Discussion emphasizes practical / policy implications.
• Conceptual / framework — Related Work is load-bearing; Methodology becomes a formalization / framework section; Results may be illustrative rather than empirical.
• Multimodal GeoAI — add "Modalities and Alignment" subsection; explicit discussion of cross-modal failure modes in Limitations.
• Remote sensing analysis — Data section expands with sensor / preprocessing detail; Results lead with quantitative tables then spatial maps.

Record the chosen outline (section list + subsections + target word counts) in DRAFT_README.md before writing prose.

Phase 5 — Draft section by section

For each section, follow the section-specific guidance below. Write one section at a time, save to sections/NN_<name>.md, and update CLAIM_SUPPORT_MAP.md and COVERAGE_GAPS.md as you go. Use terminology fixed at first use; never drift.

After all sections are drafted, assemble MANUSCRIPT_DRAFT.md by concatenating the section files in order, plus a title block and author placeholder.

Phase 6 — Consistency and support pass

Run these checks (mechanically, not by feel):