grind-lab-core/night_owl_research_agent/paper-review-loop

Skill: paper-review-loop

You critically review the manuscript draft in `output/manuscript/` — produced by paper-draft from `output/PAPER_PLAN.md` — and revise it into a stronger academic draft suitable for journals such as International Journal of Geographic Information Science (IJGIS), ISPRS Journal of Photogrammetry and Remote Sensing (ISPRS JPRS), Remote Sensing of Environment (RSE), and Transactions in GIS (TGIS).

Scope argument: $ARGUMENTS

This skill is the review-and-revise counterpart to paper-draft. It reads the manuscript, compares it against the plan and its evidence artifacts, diagnoses weaknesses, revises the manuscript, and emits a rich set of artifacts that help the next review cycle continue the improvement. It is not LaTeX polishing, not format compliance (that is submit-check), and not first-draft generation (that is paper-draft).

Supported manuscript types (mirrored from paper-draft):

• 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` — manuscript intent and evidence blueprint.
• MS_DIR = `output/manuscript/` — drafts live here.
• MAIN_DRAFT = `output/manuscript/MANUSCRIPT_DRAFT.md` — current manuscript.
• SECTIONS_DIR = `output/manuscript/sections/` — per-section drafts.
• TARGET_VENUE — read from PAPER_PLAN.md §0/§2, else research_contract.md, else default IJGIS.
• PAPER_TYPE — read from PAPER_PLAN.md §21, else infer from §5 contributions, else fall back to the framing recorded by paper-draft in DRAFT_README.md.
• APPROVED_CLAIMS = `memory/APPROVED_CLAIMS.md` — the only source of verified numeric/empirical claims.
• LIT_REVIEW_REPORT = `output/LIT_REVIEW_REPORT.md` — consolidated literature review (Findings, Synthesis, Gap Analysis).
• FIGURE_MANIFEST = `output/figures/FIGURE_MANIFEST.md` — figures that actually exist.
• REVIEWER_MODEL = `gpt-5.4` — used via Codex MCP for adversarial section-level review (optional; skill is fully operational without it).
• REVIEW_MODE — one of integrated (default), structural, argument, novelty, methods, results-discussion, journal-fit, language.
• REVISION_MODE — one of full, partial, conservative. Chosen in Phase 3; may be overridden inline.
• MAX_ROUNDS = 3 — cap per invocation to avoid unbounded work. Quality is set by artifact content, not round count.
• LOOP_STATE = `output/manuscript/REVIEW_LOOP_STATE.json` — persists round, mode, last scores, unresolved issue ids across sessions.
• HUMAN_CHECKPOINT — read from CLAUDE.md Control Flags, default true. When true, pause after diagnosis and before committing revisions; when false, run to completion.

Override inline: /paper-review-loop all — venue: ISPRS, mode: methods, revision: conservative, rounds: 1.

Argument forms:

• all — review + revise the whole manuscript.
• abstract · introduction · related-work · data · methods · experiments · results · discussion · limitations · conclusion · declarations — scope to one section.
• A MODE: prefix — e.g. mode:novelty, mode:journal-fit. Combines with a section scope.
• A path to a manuscript file — review that file instead of MAIN_DRAFT.

Core Philosophy

1. Review is a means, revision is the deliverable. Critique that does not land as an improved draft is half the job. Every major issue must be either fixed in the revised manuscript or recorded with an explicit reason it could not be fixed.
2. Evidence binds claims. The manuscript may only assert what is supported by APPROVED_CLAIMS.md, entries in output/EXPERIMENT_LOG.md, rows in PAPER_PLAN.md §12, or the paper-cache synthesis. Anything else is softened, flagged, or cut.
3. Plan is intent, evidence is truth. Discrepancies between the manuscript and PAPER_PLAN.md matter; discrepancies between the manuscript and the underlying evidence matter more. When they conflict, evidence wins.
4. Journal voice is non-negotiable. IJGIS / ISPRS JPRS / RSE / TGIS reviewers expect formal, precise, rigor-first prose. No hype, no startup framing, no vague "leverage the power of."
5. Diagnose, prioritize, revise. Major issues first (gap, novelty, evidence, methods clarity, limitations), moderate issues second (structure, transitions, terminology), minor issues last (polish). Do not fix sentence-level wording while structural arguments are still broken.
6. Generator-evaluator separation respected in reverse. This skill may rewrite prose, but the evaluation that drives revision should come from a cold reading — either via the external reviewer (Codex MCP) or from a fresh sub-agent reading only the draft and the plan, not the prior drafting context.
7. Readiness-aware behavior. On skeletal drafts, do not pretend the manuscript is close to submission. Produce a revision plan and a conservative refinement of supported sections instead.
8. Loops are monotonic. Each round should strictly improve the manuscript on at least one named axis, and never silently reintroduce a previously-resolved issue.

Inputs

Primary

• `output/manuscript/MANUSCRIPT_DRAFT.md` — the integrated manuscript from paper-draft.
• `output/manuscript/sections/*.md` — per-section drafts with front matter (section, mode, word_target).
• `output/PAPER_PLAN.md` — manuscript intent and claim-to-evidence map (§12 especially).

Companion artifacts from paper-draft (read on demand)

• output/manuscript/DRAFT_README.md — mode, venue, paper type, readiness, per-section fidelity.
• output/manuscript/CLAIM_SUPPORT_MAP.md — the claim-to-evidence rows this skill must re-verify.
• output/manuscript/COVERAGE_GAPS.md — missing experiments, figures, citations flagged at draft time.
• output/manuscript/CITATION_GAPS.md — claims missing citations.
• output/manuscript/SECTION_NOTES.md — per-section scope decisions and softened claims.
• output/manuscript/REVISION_NOTES.md — unfinished items from the drafting pass.
• output/manuscript/ABSTRACT_DRAFT.md — stand-alone abstract.

Evidence and context (read as needed)

• research_contract.md, program.md — active idea and constraints.
• memory/APPROVED_CLAIMS.md, output/LIT_REVIEW_REPORT.md (Gap Analysis + Synthesis sections).
• memory/paper-cache/*.json — bibliographic + finding records.
• output/EXPERIMENT_LOG.md, output/EXPERIMENT_PLAN.md, output/PROJ_NOTES.md.
• output/spatial-analysis/ — ESDA and diagnostic reports.
• output/figures/FIGURE_MANIFEST.md, output/figures/FIGURE_CAPTIONS.md.
• output/AUTO_REVIEW.md — prior adversarial-review scores and pending fixes.
• templates/giscience/, templates/remote_sensing/, templates/geoscience/ — venue guides.
• skills/knowledge/academic-writing.md, skills/knowledge/apa-citations.md, skills/knowledge/spatial-methods.md, skills/knowledge/geoai-domain.md.
• skills/shared-references/writing-principles.md, skills/shared-references/venue-checklists.md — load only when acting on Abstract / Introduction / Related Work / journal-fit.

Prior-loop state

• output/manuscript/REVIEW_LOOP_STATE.json — round counter, unresolved issue ids, prior scores, timestamp.
• output/manuscript/REVIEW_REPORT.md, MAJOR_ISSUES.md, MINOR_ISSUES.md, REVISION_LOG.md, NEXT_LOOP_PRIORITIES.md — if present, treated as the incoming queue for this round.

Outputs

All outputs live under output/manuscript/. Filenames are stable across rounds (the skill overwrites); rounds are distinguished by entries inside the files, not by filename suffixes.

File-naming conventions are inherited from paper-draft: two-digit section prefixes, no _v2 suffixes, prior versions preserved via git not filenames.

Workflow

The skill has eight phases. Phases 1–4 are diagnosis; Phase 5 is the optional human checkpoint; Phases 6–7 are revision and verification; Phase 8 is handoff. On tight scopes (e.g. mode:language), phases can be compressed but not skipped.

Phase 1 — Load state and scope

1. Read CLAUDE.md Control Flags. Honour HUMAN_CHECKPOINT.
2. If REVIEW_LOOP_STATE.json exists with status: in_progress and timestamp within 24 hours: resume. Increment round. Read prior REVIEW_REPORT.md, MAJOR_ISSUES.md, NEXT_LOOP_PRIORITIES.md as the incoming queue.
3. If not resuming: initialize round = 1, load scope from $ARGUMENTS.
4. Resolve REVIEW_MODE and section scope:

• No mode given → integrated.
• mode:<x> given → use that mode; other phases still run but are minimized.

1. Locate the manuscript:

• If $ARGUMENTS is a path → use it.
• Else use MAIN_DRAFT. If absent, emit a stub REVIEW_REPORT.md explaining that paper-draft must run first, and stop.

Phase 2 — Read manuscript and its companion artifacts

Read in this order (cheap → expensive):

1. DRAFT_README.md — get declared DRAFT_MODE (full / partial / skeleton), venue, paper type, readiness signals, and per-section fidelity.
2. MANUSCRIPT_DRAFT.md and relevant sections/*.md. Determine whether the draft is full, partial, or skeletal regardless of what DRAFT_README.md claims (cross-check against actual content length, [PLACEHOLDER ...] blocks, and [CITE: ...] tags).
3. CLAIM_SUPPORT_MAP.md — pull the claim-to-evidence rows; this is the backbone of the claim-risk audit.
4. COVERAGE_GAPS.md, CITATION_GAPS.md, SECTION_NOTES.md, REVISION_NOTES.md — known-at-draft-time weaknesses.
5. ABSTRACT_DRAFT.md — the stand-alone abstract.

Phase 3 — Cross-check against PAPER_PLAN.md

Open PAPER_PLAN.md. For each plan section that drives the draft, answer a specific question and record the answer in SECTION_REVIEW_NOTES.md: